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.
12 @c Translators: Ludovic Sardain
13 @c Translation checkers: Jean-Yves Baudais, Valentin Villenave, John Mandereau, Jean-Charles Malahieude
15 @node Working on LilyPond projects
16 @chapter Working on LilyPond projects
18 Cette section explique comment résoudre ou éviter certains problèmes
19 courants. Si vous avez de l'expérience en programmation, beaucoup de
20 ces astuces peuvent vous paraître évidentes, mais vous ne perdrez tout
21 de même pas votre temps à lire ce chapitre.
24 * Suggestions for writing LilyPond files::
25 * Saving typing with identifiers and functions::
27 * Updating old files::
28 * Troubleshooting (taking it all apart)::
32 @node Suggestions for writing LilyPond files
33 @section Suggestions for writing LilyPond files
35 Maintenant vous êtes prêt à travailler sur de plus gros fichiers
36 LilyPond --- des pièces entières, et plus seulement les petits
37 exemples du tutoriel. Mais comment devriez-vous vous y prendre ?
39 Tant que LilyPond parvient à comprendre vos fichiers et produit le
40 résultat que vous souhaitez, peu importe la manière dont le code est
41 organisé. Néanmoins, quelques critères doivent être pris en compte
42 lorsque l'on écrit un fichier LilyPond.
45 @item Si vous faites une erreur, la structure même du fichier LilyPond
46 peut permettre de la localiser plus ou moins facilement.
48 @item Et si vous souhaitez partager vos fichiers avec quelqu'un
49 d'autre, ou si vous souhaitez modifier vos propres fichiers dans
50 quelques années ? Si certains fichiers LilyPond sont compréhensibles
51 au premier coup d'oeil, d'autres vous feront vous arracher les cheveux
54 @item Et si vous souhaitez mettre à jour votre fichier pour
55 l'utiliser avec une version plus récente de LilyPond ? La syntaxe du
56 langage d'entrée change parfois lorsque LilyPond s'améliore. La
57 plupart des changements peuvent être appliqués automatiquement avec
58 @code{convert-ly}, mais quelques-uns peuvent requérir une intervention
59 manuelle. Vos fichiers LilyPond peuvent être structurés de manière à
60 faciliter leur mise à jour.
64 * General suggestions::
65 * Typesetting existing music::
69 @node General suggestions
70 @subsection General suggestions
72 Voici quelques conseils qui peuvent vous éviter certains problèmes ou
76 @item @strong{Ajoutez le numéro de version dans chaque fichier}.
77 Notez que chaque fichier modèle contient une ligne @code{\version
78 "2.11.32"}. Nous vous conseillons fortement d'inclure cette ligne,
79 même pour de petits fichiers. Par expérience, il est très difficile
80 de se rappeler quelle version de LilyPond on utilisait quelques
81 années auparavant. L'utilitaire @command{convert-ly} demande que vous
82 spécifiiez la version de LilyPond vous utilisiez alors.
84 @item @strong{Ajoutez des contrôles}: @ruser{Bar check}, @ruser{Octave
85 check} et @ruser{Barnumber check}. Si vous avez ajouté des contrôles de
86 loin en loin, et que vous faites une erreur, vous pourrez la retrouver
87 plus rapidement. @qq{De loin en loin}, qu'est-ce à dire ? Cela
88 dépend de la complexité de la musique. Pour de la musique très
89 simple, peut-être une ou deux fois. Pour de la musique très complexe,
90 peut-être à chaque mesure.
92 @item @strong{Une mesure par ligne de texte}. Si la musique en elle-même ou
93 le résultat que vous désirez contient quelque chose de compliqué, il
94 est souvent bon de n'écrire qu'une seule mesure par ligne. Économiser
95 de la place en tassant huit mesures par ligne, ça ne vaut pas vraiment
96 le coup si l'on doît corriger vos fichiers.
98 @item @strong{Ajoutez des commentaires}. Utilisez soit des
99 numéros de mesure (assez souvent), soit des références au contenu
100 musical --- @qq{second thème des violons}, @qq{quatrième variation}, etc.
101 Vous pouvez ne pas avoir besoin des commentaires lorsque vous écrivez
102 une pièce pour la première fois, mais si vous souhaitez y revenir deux
103 ou trois ans plus tard pour changer quelque chose, ou si vous donnez
104 le fichier source à un ami, ce sera beaucoup plus difficile de
105 déterminer vos intentions ou la manière dont votre fichier est
106 structuré si vous n'y avez pas adjoint de commentaires.
108 @item @strong{Indentez les accolades}. Beaucoup de problèmes
109 viennent d'un défaut de parité entre @code{@{} et @code{@}}.
111 @item @strong{Séparez les affinages de mise en forme} de la musique
112 elle-même. Voyez @ruser{Saving typing with identifiers and functions} et
113 @ruser{Style sheets}.
118 @node Typesetting existing music
119 @subsection Typesetting existing music
121 Si vous saisissez de la musique à partir d'une partition existante,
122 c'est-à-dire de la musique déjà écrite,
126 @item n'entrez qu'un seul système de la partition originale
127 à la fois --- mais toujours une seule mesure par ligne de texte ---,
128 et vérifiez chaque système lorsqu'il est terminé. Vous pouvez
129 utiliser la commande @code{showLastLength} pour accélérer la
130 compilation --- voir @ruser{Skipping corrected music} ;
132 @item définissez @code{mBreak = @{\break @}} et insérez
133 @code{\mBreak} dans le fichier d'entrée pour obtenir des sauts de
134 ligne identiques à la partition originale. Cela facilite la
135 comparaison entre la partition originale et la partition de
136 LilyPond. Lorsque vous avez fini de relire votre musique, vous pouvez
137 définir @code{mBreak = @{ @}} pour enlever tous ces sauts de ligne, et
138 laisser LilyPond placer les sauts de ligne selon son propre algorithme.
144 @subsection Large projects
146 Lorsque l'on travaille sur un gros projet, il devient vital
147 de structurer clairement ses fichiers LilyPond.
151 @item @strong{Utilisez un identificateur pour chaque voix},
152 avec un minimum de structure dans la définition. La structure de la
153 section @code{\score} est la plus susceptible de changer, notamment
154 dans une nouvelle version de LilyPond, alors que la définition du
155 @code{violon} l'est beaucoup moins.
158 violin = \relative c'' @{
171 @item @strong{Séparez les retouches} des définitions de
172 musique. Ce conseil a été vu dans @ruser{General suggestions},
173 mais pour les projets d'importance c'est absolument vital. Nous
174 pouvons avoir besoin de changer la définition de
175 @code{fthenp}, mais dans ce cas nous n'aurons besoin de le faire
176 qu'une seule fois, et nous pourrons encore éviter de
177 modifier quoi que ce soit à l'intérieur de la définition
182 \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
183 violin = \relative c'' @{
191 @node Saving typing with identifiers and functions
192 @section Saving typing with identifiers and functions
195 @cindex identificateurs
197 Jusqu'à maintenant, vous avez vu ce type de code :
199 @lilypond[quote,verbatim,ragged-right]
200 hornNotes = \relative c'' { c4 b dis c }
208 Vous comprendrez combien cela peut être utile pour écrire de la
209 musique minimaliste :
211 @lilypond[quote,verbatim,ragged-right]
212 fragA = \relative c'' { a4 a8. b16 }
213 fragB = \relative c'' { a8. gis16 ees4 }
214 violin = \new Staff { \fragA \fragA \fragB \fragA }
222 Cependant, vous pouvez aussi utiliser ces identificateurs
223 --- aussi connus sous le nom de variables, macros, ou commandes
224 (définies par l'utilisateur) --- pour des retouches :
226 @lilypond[quote,verbatim,ragged-right]
227 dolce = \markup{ \italic \bold dolce }
228 padText = { \once \override TextScript #'padding = #5.0 }
229 fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
230 violin = \relative c'' {
232 c4._\dolce b8 a8 g a b |
234 c4.^"hi there!" d8 e' f g d |
235 c,4.\fthenp b8 c4 c-. |
242 \layout{ragged-right=##t}
246 Ces identificateurs sont évidemment utiles pour économiser de la
247 frappe. Mais ils peuvent l'être même si vous ne les utilisez qu'une
248 seule fois : ils réduisent la complexité. Regardons l'exemple
249 précédent sans aucun identificateur. C'est beaucoup plus laborieux à
250 lire, et particulièrement la dernière ligne.
253 violin = \relative c'' @{
255 c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
256 \once \override TextScript #'padding = #5.0
257 c4.^"hi there!" d8 e' f g d |
258 c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
259 \hspace #0.1 \dynamic p @} b8 c4 c-. |
264 Jusqu'ici nous avons vu des substitutions statiques : quand LilyPond
265 rencontre @code{\padText}, il le remplace par le contenu que nous lui
266 avons défini --- c'est-à-dire le contenu à droite de @code{padText=}.
268 LilyPond gère également des substitutions non-statiques --- vous
269 pouvez les voir comme des fonctions.
271 @lilypond[quote,verbatim,ragged-right]
273 #(define-music-function (parser location padding) (number?)
275 \once \override TextScript #'padding = #$padding
283 c4^"piu mosso" fis a g
287 Utiliser les identificateurs est aussi un bon moyen pour vous épargner
288 du travail si la syntaxe de LilyPond change un jour --- voir
289 @ruser{Updating old files}. Si vous avez une seule définition, par
290 exemple @code{\dolce}, pour tous vos fichiers (voir @ruser{Style
291 sheets}), et que la syntaxe change, alors vous n'aurez qu'à mettre à
292 jour votre seule définition @code{\dolce}, au lieu de devoir modifier
293 chaque fichier @code{.ly}.
297 @section Style sheets
299 La sortie que produit LilyPond peut être largement modifiée --- voir
300 @ruser{Tweaking output} pour plus de détails. Mais que faire si vous
301 avez beaucoup de fichiers auxquels vous souhaitez appliquer vos
302 retouches ? Ou si vous souhaitez simplement séparer les retouches de
303 la musique elle-même ? Rien de plus facile.
305 Prenons un exemple. Ne vous inquiétez pas si vous ne comprenez pas
306 les parties avec tous les @code{#()}. Celles-ci sont expliquées dans
307 @ruser{Advanced tweaks with Scheme}.
309 @lilypond[quote,verbatim,ragged-right]
310 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
311 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
312 tempoMark = #(define-music-function (parser location markp) (string?)
314 \once \override Score . RehearsalMark #'self-alignment-X = #left
315 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
316 \mark \markup { \bold $markp }
321 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
322 \tempoMark "Poco piu mosso"
323 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
327 Il y a quelques problèmes de chevauchement ; nous allons arranger
328 cela en utilisant les techniques de @ruser{Moving objects}. On peut
329 aussi faire quelque chose pour les définitions de @code{mpdolce}
330 et @code{tempoMark}. Elles produisent le résultat que nous désirons,
331 mais nous pourrions aussi vouloir les utiliser dans une autre pièce.
332 Il suffirait de les copier et les coller au début de chaque
333 fichier, mais c'est fastidieux. De plus, cela laisse les définitions
334 dans nos fichiers de musique, et je trouve personnellement tous ces
335 @code{#()} assez laids. Stockons-les dans un autre fichier :
338 %%% enregistrez ceci dans un fichier nommé "definitions.ly"
339 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
340 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
341 tempoMark = #(define-music-function (parser location markp) (string?)
343 \once \override Score . RehearsalMark #'self-alignment-X = #left
344 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
345 \mark \markup @{ \bold $markp @}
349 Maintenant, modifions notre musique (enregistrez ce fichier
350 sous @file{"musique.ly"}).
352 @c We have to do this awkward example/lilypond-non-verbatim
353 @c because we can't do the \include stuff in the manual.
356 \include "definitions.ly"
360 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
361 \once \override Score.RehearsalMark #'padding = #2.0
362 \tempoMark "Poco piu mosso"
363 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
367 @lilypond[quote,ragged-right]
368 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
369 #:line(#:dynamic "mp" #:text #:italic "dolce" )))
370 tempoMark = #(define-music-function (parser location markp) (string?)
372 \once \override Score . RehearsalMark #'self-alignment-X = #left
373 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
374 \mark \markup { \bold $markp }
379 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
380 \once \override Score.RehearsalMark #'padding = #2.0
381 \tempoMark "Poco piu mosso"
382 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
386 C'est mieux, mais effectuons encore quelques retouches. Le glissando
387 est peu visible, c'est pourquoi nous allons l'épaissir et le
388 rapprocher des têtes de notes. Déplaçons l'indication métronomique
389 au-dessus de la clef, au lieu de la laisser au-dessus de la première
390 note. Et pour finir, mon professeur de composition déteste les
391 chiffrages de mesure en @qq{C}, nous allons donc le transformer en @qq{4/4}.
393 Cependant, ne changez pas le fichier @file{musique.ly}. Remplacez le
394 fichier @file{definitions.ly} par ceci :
398 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
399 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
400 tempoMark = #(define-music-function (parser location markp) (string?)
402 \once \override Score . RehearsalMark #'self-alignment-X = #left
403 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
404 \mark \markup @{ \bold $markp @}
409 \override MetronomeMark #'extra-offset = #'(-9 . 0)
410 \override MetronomeMark #'padding = #'3
413 \override TimeSignature #'style = #'numbered
416 \override Glissando #'thickness = #3
417 \override Glissando #'gap = #0.1
422 @lilypond[quote,ragged-right]
423 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
424 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
425 tempoMark = #(define-music-function (parser location markp) (string?)
427 \once \override Score . RehearsalMark #'self-alignment-X = #left
428 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
429 \mark \markup { \bold $markp }
434 \override MetronomeMark #'extra-offset = #'(-9 . 0)
435 \override MetronomeMark #'padding = #'3
438 \override TimeSignature #'style = #'numbered
441 \override Glissando #'thickness = #3
442 \override Glissando #'gap = #0.1
448 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
449 \once \override Score.RehearsalMark #'padding = #2.0
450 \tempoMark "Poco piu mosso"
451 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
455 C'est encore mieux ! Mais supposons maintenant que je veuille publier
456 cette pièce. Mon professeur de composition n'aime pas les chiffrages
457 de mesure en @qq{C}, mais moi je les aime bien. Copions l'actuel
458 @file{definitions.ly} dans le fichier @file{publication-web.ly}, et
459 modifions ce dernier. Puisque la musique est destinée à produire un
460 fichier PDF affiché sur écran, nous allons aussi augmenter la taille
465 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
466 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
467 tempoMark = #(define-music-function (parser location markp) (string?)
469 \once \override Score . RehearsalMark #'self-alignment-X = #left
470 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
471 \mark \markup @{ \bold $markp @}
474 #(set-global-staff-size 23)
477 \override MetronomeMark #'extra-offset = #'(-9 . 0)
478 \override MetronomeMark #'padding = #'3
483 \override Glissando #'thickness = #3
484 \override Glissando #'gap = #0.1
489 @lilypond[quote,ragged-right]
490 mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
491 #:line( #:dynamic "mp" #:text #:italic "dolce" )))
492 tempoMark = #(define-music-function (parser location markp) (string?)
494 \once \override Score . RehearsalMark #'self-alignment-X = #left
495 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
496 \mark \markup { \bold $markp }
499 #(set-global-staff-size 23)
502 \override MetronomeMark #'extra-offset = #'(-9 . 0)
503 \override MetronomeMark #'padding = #'3
506 \override Glissando #'thickness = #3
507 \override Glissando #'gap = #0.1
513 a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
514 \once \override Score.RehearsalMark #'padding = #2.0
515 \tempoMark "Poco piu mosso"
516 cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
520 Il ne nous reste plus qu'à remplacer @code{\include "definitions.ly"}
521 par @code{\include "publication-web.ly"} dans notre fichier de musique.
523 Il est possible, bien sûr, de rendre cela encore plus pratique. Nous
524 pourrions créer un fichier @file{definitions.ly} qui ne contiendrait
525 que les définitions de @code{mpdolce} et de @code{tempoMark}, un
526 fichier @file{publication-web.ly} qui ne contiendrait que la section
527 @code{layout} décrite ci-dessus et un fichier @file{universite.ly} qui
528 ne contiendrait que les retouches pour produire le résultat que mon
529 professeur préfère. Le début du fichier @file{musique.ly} ressemblerait
533 \include "definitions.ly"
535 %%% Décommentez seulement une de ces deux lignes !
536 \include "publication-web.ly"
537 %\include "universite.ly"
540 Cette approche peut être utile même si vous ne produisez qu'un seul
541 jeu de partitions. J'utilise personnellement une demi-douzaine de
542 fichiers de @qq{feuille de style} pour mes projets. Je commence
543 chaque fichier de musique par @code{\include "../global.ly"} qui contient :
547 \version @w{"@version{}"}
548 #(ly:set-option 'point-and-click #f)
549 \include "../init/init-defs.ly"
550 \include "../init/init-mise-en-page.ly"
551 \include "../init/init-en-tetes.ly"
552 \include "../init/init-papier.ly"
555 @node Updating old files
556 @section Updating old files
558 La syntaxe de LilyPond change de temps en temps. Ces changements de
559 syntaxe du langage d'entrée accompagnent les améliorations du
560 logiciel. Ces changements sont parfois destinés à rendre les fichiers
561 plus faciles à lire et à écrire, ou permettent d'intégrer de nouvelles
564 LilyPond est fourni avec un utilitaire qui facilite cette mise à
565 jour : @command{convert-ly}. Pour savoir comment utiliser ce programme,
566 voir @rprogram{Updating files with convert-ly}.
568 Malheureusement, @command{convert-ly} ne peut pas réaliser toutes les
569 modifications. Il s'occupe des changements qui ne requièrent qu'une
570 simple substitution de texte --- comme @code{raggedright} devenant
571 @code{ragged-right} ---, les autres étant trop compliqués à effectuer.
572 Les changements de syntaxe qui ne sont pas gérés par @command{convert-ly}
573 sont énumérés dans @rprogram{Updating files with convert-ly}.
575 Par exemple, dans les versions 2.4 et antérieures de LilyPond,
576 les accents et les lettres non anglaises étaient entrées en
577 utilisant LaTeX --- par exemple, @samp{No\"el}. À partir de la
578 version 2.6, le caratère @samp{ë} doit être entré directement
579 dans le fichier LilyPond comme caractère UTF-8.
580 @code{convert-ly} ne peut pas changer tous les caractères
581 LaTeX en caractères UTF-8 ; vous devez mettre à jour vos vieux
582 fichiers LilyPond manuellement.
586 @node Troubleshooting (taking it all apart)
587 @section Troubleshooting (taking it all apart)
589 Tôt ou tard, vous écrirez un fichier que LilyPond ne peut pas
590 compiler. Les messages que LilyPond affiche peuvent vous aider à
591 trouver l'erreur, mais dans beaucoup de cas vous aurez besoin de faire
592 quelques recherches pour déterminer la source du problème.
594 Pour ce faire, les outils les plus puissants sont le commentaire de
595 fin de ligne, indiqué par @code{%}, et le commentaire multilignes (ou
596 bloc de commentaire), indiqué par @code{%@{ ... %@}}. Si vous ne
597 pouvez localiser le problème, commencez par mettre en commentaire de
598 grandes parties de votre fichier d'entrée. Après avoir mis en
599 commentaire une section, essayez de compiler à nouveau. Si cela
600 fonctionne, c'est que le problème se situe dans cette partie du
601 fichier. Si cela ne fonctionne pas, continuez à mettre en commentaire
602 d'autres sections, jusqu'à ce que vous ayez quelque chose qui compile.
604 Dans un cas extrême, vous pourriez en arriver à
618 c'est-à-dire un fichier sans aucune musique.
620 Si cela arrive, ne vous découragez pas. Décommentez un peu, la partie
621 de basse par exemple, et voyez si ça fonctionne. Si ce n'est pas le
622 cas, placez en commentaire toute la partie de basse, mais laissez
623 @code{\basse} décommenté dans le bloc @code{\score}.
626 basse = \relative c' @{
634 Maintenant commencez à décommenter petit à petit le partie de
635 @code{basse} jusqu'à ce que vous localisiez la ligne qui pose
638 Une autre technique de déboguage très utile est la construction
640 de @ruser{Minimal examples}.
643 d'@ruser{Minimal examples}.
647 @node Minimal examples
648 @section Minimal examples
650 Un exemple minimal est un exemple de code aussi court que possible.
651 De tels exemples sont bien plus compréhensibles que des exemples
652 longs. Les exemples minimaux sont utilisés pour
655 @item les rapports de bogue,
656 @item les demandes d'aide sur les listes de diffusion,
658 @uref{http://lsr@/.dsi@/.unimi@/.it/,LilyPond Snippet Repository}.
661 Pour construire un exemple minimal, la règle est très simple : enlevez
662 tout ce qui n'est pas nécessaire. Il est préférable de commenter les
663 lignes non nécessaires plutôt que de les effacer : ainsi, si vous vous
664 apercevez que certaines étaient @emph{réellement} nécessaires, vous
665 pouvez les décommenter au lieu de les resaisir.
667 Il y a deux exceptions à cette règle du strict nécessaire :
670 @item incluez le numéro de @code{\version} en début de fichier
671 @item si possible, utilisez @code{\paper@{ ragged-right=##t @}} au
672 début de votre exemple.
675 Tout l'intérêt d'un exemple minimal réside dans sa facilité de lecture :
677 @item évitez d'utiliser des notes, armures ou métriques compliquées, à
678 moins que vous ne vouliez montrer quelque chose en rapport avec
680 @item n'utilisez pas de commandes @code{\override} sauf si elles font
681 l'intérêt de l'exemple.