1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
4 Translation of GIT committish: 0a003d729ded8b728bf627c87c196719676dba6b
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @c Translators: Jean-Charles Malahieude
14 @c Translation checkers:
16 @node Exécution de lilypond
17 @chapter Exécution de @command{lilypond}
18 @translationof Running lilypond
20 Ce chapitre passe en revue ce qui se passe lorsque vous lancez LilyPond.
23 * Utilisation habituelle::
24 * Utilisation en ligne de commande::
26 * Quelques erreurs des plus courantes::
29 @node Utilisation habituelle
30 @section Utilisation habituelle
31 @translationof Normal usage
33 La plupart des utilisateurs de LilyPond le font au travers d'une
34 interface graphique (@emph{GUI} pour @emph{graphical user interface}).
35 Si vous ne l'avez pas encore parcouru, lisez le @rlearning{Tutoriel}.
36 Si vous utilisez un éditeur alternatif pour rédiger vos fichiers
37 LilyPond, référez-vous à la documentation de celui-ci.
40 @node Utilisation en ligne de commande
41 @section Utilisation en ligne de commande
42 @translationof Command-line usage
44 Nous nous intéresserons ici aux spécificités de LilyPond employé en
45 ligne de commande. La ligne de commande permet de faire appel à
46 certaines options particulières. D'autre part, certains utilitaires
47 associés, tel que @code{midi2ly}, ne sont disponibles qu'en ligne de
50 Par @qq{ligne de commande}, nous entendons l'interface de commande du
51 système. Les utilisateurs de Windows seront certainement plus familiers
52 des termes @qq{fenêtre DOS} ou @qq{invite de commande}. Quant aux
53 utilisateurs de MacOS X, ils connaissent assurément les termes
54 @qq{console} et @qq{terminal}. Les paramétrages spécifiques au système
55 MacOS font l'objet d'un @rwebnamed{MacOS X,chapitre particulier}.
57 Notre propos n'est pas ici d'expliquer ce qu'est l'interface de
58 commande pour un système informatique ni comment elle fonctionne.
59 Aussi, si vous ne savez de quoi il retourne, nous vous renvoyons aux
60 nombreuses documentations que vous pourrez trouver sur ce sujet.
63 * Lancement de lilypond::
64 * Options basiques de lilypond::
65 * Options avancées de lilypond::
66 * Variables d'environnement::
67 * Exécution de LilyPond en mode protégé::
71 @node Lancement de lilypond
72 @unnumberedsubsec Lancement de @command{lilypond}
73 @translationof Invoking LilyPond
75 L'exécutable @command{lilypond} en ligne de commande se lance ainsi :
78 lilypond [@var{option}]@dots{} @var{fichier}@dots{}
81 Lorsque le fichier est fourni sans extension, LilyPond présume qu'il
82 s'agit de @file{.ly}. Pour interpréter directement l'entrée standard
83 (@emph{stdin}), fournissez un tiret (@code{-}) en lieu et place de
86 Le traitement de @file{monfichier.ly} produira @file{monfichier.ps} et
87 @file{monfichier.pdf}. Vous pouvez spécifier plusieurs fichiers à la
88 fois ; ils seront traités indépendamment les uns des
89 autres.@footnote{Le statut de GUILE n'étant pas réinitialisé après
90 traitement d'un fichier @file{.ly}, veillez à ne pas modifier les
91 réglages par défaut du système à partir d'assertions en Scheme.}
93 Lorsque @file{monfichier.ly} contient plus d'une section @code{\book},
94 les fichiers produits -- à partir du deuxième -- seront numérotés. Par
95 ailleurs, la valeur affectée à @code{output-suffix} sera insérée entre la
96 racine et le numéro. Par exemple, un fichier @var{racine} qui
100 #(define output-suffix "violon")
102 #(define output-suffix "cello")
107 fournira grâce à LilyPond @file{@var{racine}-violon.pdf} et
108 @file{@var{racine}-cello-1.pdf}.
111 @unnumberedsubsubsec Utilisation de LilyPond avec les fonctionnalités standard de l'interpréteur
112 @translationof Using LilyPond with standard shell features
114 Dans la mesure où LilyPond est une application qui fonctionne en ligne
115 de commande, les fonctionnalités de l'interpréteur utilisé pour lancer
116 LilyPond peuvent se révéler utiles.
124 traitera tous les fichiers LilyPond présent dans le répertoire en cours.
126 Rediriger, par exemple dans un fichier, ce qui est émis à l'écran peut
130 lilypond fichier.ly 1> stdout.log
132 lilypond fichier.ly 2> stderr.log
134 lilypond fichier.ly &> tous.log
138 redirigeront respectivement le « verbiage normal », les erreurs ou tout,
139 dans un fichier texte.
141 Consultez avant tout la documentation de votre interpréteur habituel
142 -- terminal, console, etc. -- pour vérifier qu'il prend en charge les
143 options dans cette syntaxe.
146 @node Options basiques de lilypond
147 @unnumberedsubsec Options basiques de @command{lilypond}
148 @translationof Basic command line options for LilyPond
150 @cindex lancement de @command{lilypond}
151 @cindex ligne de commande, options pour @command{lilypond}
152 @cindex options, ligne de commande
156 Différentes options sont disponibles en ligne de commande :
160 @item -d, --define-default=@var{variable}=@var{valeur}
161 Voir @ref{Options avancées de lilypond}.
163 @cindex Scheme, évaluation d'expression
164 @cindex expression Scheme, évaluation
165 @item -e, --evaluate=@var{expr}
166 Évalue l'expression Scheme @var{expr} avant d'analyser tout fichier
167 @file{.ly}. Lorsque vous spécifiez l'option @option{-e} à plusieurs
168 reprises, l'évaluation sera faite en séquence.
170 Dans la mesure où l'expression est évaluée par le module
171 @code{guile-user}, vous devrez, dès lors que @var{expr} utilise des
172 définitions, spécifier
175 lilypond -e '(define-public a 42)'
179 en ligne de commande, et ajouter la ligne
182 #(use-modules (guile-user))
186 en tête de votre fichier @file{.ly}.
188 @warning{Les utilisateurs de Windows doivent utiliser des guillemets
189 doubles @code{"} en lieu et place des guillemets simples @code{'}.}
190 @c Match " in context-sensitive editors
192 @cindex sortie, format
193 @cindex format de sortie
194 @item -f, --format=@var{format}
195 Détermine le format à produire. Il peut s'agir de @code{ps}, @code{pdf}
198 Exemple : @code{lilypond -fpng @var{monfichier}.ly}
201 Affiche un résumé des commandes.
203 @item -H, --header=@var{CHAMP}
204 Recopie le champ d'entête dans le fichier @file{RACINE.@var{CHAMP}}.
206 @item -i, --init=@var{fichier}
207 Définit @var{fichier} (par défaut @file{init.ly}) en tant que fichier
210 @cindex recherche de fichier
211 @cindex chemin de recherche
212 @item -I, --include=@var{répertoire}
213 Ajoute @var{répertoire} au chemin de recherche pour les inclusions.
215 Vous pouvez mentionner plusieurs fois l'option @option{-I}, auquel cas
216 la recherche commencera dans le premier répertoire inclus et, si le
217 fichier en question ne s'y trouve pas, les répertoires suivants seront
218 examinés l'un après l'autre.
220 @cindex chroot jail, fonctionnement
221 @item -j, --jail=@var{user},@var{group},@var{jail},@var{dir}
222 Lance @command{lilypond} dans un environnement protégé.
224 L'option @option{--jail} est une alternative qui offre plus de
225 flexibilité que l'option @option{--safe} lorsque LilyPond est installé
226 sur un serveur web ou traite des fichiers externes -- voir
227 @ref{Options avancées de lilypond}.
229 L'option @option{--jail} va détourner la racine de @command{lilypond}
230 sur @var{jail} juste avant d'effectuer la compilation à proprement
231 parler. L'utilisateur et le groupe sont modifiés en conséquence, et le
232 répertoire en cours devient @var{dir}. Ces réglages assurent -- du
233 moins en théorie -- l'impossibilité de s'échapper de la cellule. Notez
234 cependant que, pour que l'option @option{--jail} soit fonctionnelle,
235 @command{lilypond} doit être lancé en tant qu'administrateur -- ce qui
236 se réalise aisément à l'aide de la commande @command{sudo}.
238 La création d'un environnement sécurisé requiert quelques précautions
239 dans la mesure où LilyPond doit disposer de tout ce dont il a besoin
240 pour compiler le fichier source @strong{à l'intérieur de la cellule}.
241 L'ermitage, avant d'être viable, requiert donc les étapes
246 @item Création d'un système de fichiers indépendant
247 L'intérêt d'un système de fichiers dédié à LilyPond réside dans le fait
248 qu'on peut le brider à l'aide des options @code{noexec}, @code{nodev} et
249 @code{nosuid}. Il sera de fait impossible de lancer des exécutables ou
250 d'écrire sur un périphérique à partir de LilyPond. Si vous n'avez pas
251 l'intention de créer un tel système sur une partition séparée, vous
252 pouvez avoir recours à un pseudo-périphérique (@emph{loop device}) monté
253 à partir d'un simple fichier de taille raisonnable. D'autre part, le
254 recours à un système de fichiers indépendant permet de limiter l'espace
257 @item Création d'un utilisateur spécifique
258 L'utilisation de LilyPond au sein de la cellule devrait être réservé à
259 un utilisateur aux droits restreints. Il faudra donc créer un
260 utilisateur et un groupe spécifiques -- disons
261 @w{@code{lily}/@code{lily}} -- qui n'aura accès en écriture qu'à un
262 unique répertoire déterminé par la valeur de @var{dir}.
264 @item Agencement des lieux
265 LilyPond a besoin d'un certain nombre de fichiers pour pouvoir tourner
266 correctement. Ces fichiers devront donc tous se retrouver dans
267 l'environnement protégé, distribués selon la même arborescence que dans
268 le système d'origine. Ainsi l'intégralité de l'installation de LilyPond
269 (en principe @file{/usr/share/lilypond}) doit y être dupliquée.
271 En cas de problème, lancer LilyPond en utilisant @command{strace}
272 devrait vous permettre de déterminer quels fichiers manquent à l'appel.
274 @item Lancement de LilyPond
275 Dans un environnement protégé monté avec l'option @code{noexec}, il
276 est impossible de lancer un quelconque programme extérieur. LilyPond ne
277 saurait donc avoir recours à un moteur de traitement qui le mettrait
278 dans cette situation. Comme nous l'avons vu plus haut, LilyPond sera
279 lancé avec les privilèges de l'administrateur -- privilèges qu'il perdra
280 aussitôt --, ce qui peut nécessiter le recours à la commande
281 @code{sudo}. Il est par ailleurs judicieux de limiter le temps
282 processeur alloué à LilyPond -- grâce à @command{ulimit -t} par
283 exemple -- ainsi que, si votre système le permet, la taille de la
284 mémoire. Voir aussi @ref{Exécution de LilyPond en mode protégé}.
288 @cindex verbosité, définir le degré de
289 @item -l, --loglevel=@var{DEGRÉ}
290 Règle le niveau de verbosité des messages console à @var{DEGRÉ}. Les
291 différentes valeurs sont :
295 Aucun verbiage, même pas les messages d'erreur.
298 Uniquement les messages d'erreur ; pas de message d'avertissement
302 Messages d'avertissement ou d'erreur ; pas d'information de
306 Information de progression basique (réussite) et avertissements ou
310 Toutes les informations de progression, avertissements et erreurs.
312 @item INFO (par défaut)
313 Informations de progression, avertissements et erreurs, ainsi que
314 d'autres informations relatives à l'exécution.
317 Tout ce qui peut être affiché, y compris le verbiage utile au débogage.
322 @cindex répertoire de destination
323 @cindex fichier de destination
324 @item -o, --output=@var{FICHIER} ou @var{RÉPERTOIRE}
325 Détermine le nom par défaut du fichier résultant à @var{FICHIER} ;
326 lorsque l'argument @var{RÉPERTOIRE} correspond à un répertoire déjà
327 existant, c'est là que les fichiers résultants seront déposés. Le
328 suffixe adéquat sera ajouté (par ex. @code{.pdf} pour du pdf) dans tous
331 @cindex PostScript, output
332 @cindex PS (PostScript), output
334 Génère du PostScript.
336 @cindex Portable Network Graphics (PNG), output
337 @cindex PNG (Portable Network Graphics), output
339 Génère une image par page, au format PNG ; ceci sous-entend
340 l'utilisation de @option{--ps}. La résolution de l'image, en DPI, peut
341 se régler en ajoutant par exemple
346 @cindex Portable Document Format (PDF), output
347 @cindex PDF (Portable Document Format), output
349 Génère du PDF. Ceci sous-entend l'utilisation de @option{--ps}.
352 Affiche le numéro de version.
355 Active le mode verbeux : affichage de l'intégralité du chemin
356 d'accès de chaque fichier, et information des temps de traitement.
359 Affiche les informations de garantie applicables à GNU LilyPond -- il
360 est livré @strong{SANS GARANTIE} !
365 @node Options avancées de lilypond
366 @unnumberedsubsec Options avancées de @command{lilypond}
367 @translationof Advanced command line options for LilyPond
371 @item -d@var{[nom-option]}=@var{[valeur]}, --define-default=@var{[nom-option]}=@var{[valeur]}
372 Affecte la valeur Scheme @var{valeur} à l'option interne
373 @var{nom-option} du programme.
379 En l'absence de @var{valeur}, le programme utilisera @var{#t}.
380 Préfixer @var{nom-option} d'un @code{no-} vous permet de
381 désactiver une option. Ainsi,
383 @cindex point and click, ligne de commande
384 @cindex pointer-cliquer, ligne de commande
397 @noindent Voici les différentes options disponibles, ainsi que leur
400 @multitable @columnfractions .33 .16 .51
401 @item @strong{Symbole}
403 @tab @strong{Observations}
406 @item @code{anti-alias-factor}
408 @tab Adopte une résolution supérieure (selon le facteur donné),puis
409 réduit au niveau du résultat afin d'éviter les @qq{distorsions} des
412 @item @code{aux-files}
414 @tab Génère les fichiers @code{.tex}, @code{.texi} et @code{.count}
415 pour le moteur de rendu @code{EPS}.
419 @tab Détermine le format de sortie à utiliser par le moteur de
420 traitement. Les fichiers PostScript (format par défaut) incluent les
421 fontes @code{TTF}, @code{Type1} et @code{OTF}, et aucune substitution ne
422 sera opérée pour ces fontes. Si vous utilisez des jeux de caractères
423 orientaux, le fichier aura vite fait d'atteindre une taille conséquente.
427 @tab Génère du PostScript encapsulé. Chaque page (système) fera l'objet
428 d'un fichier @file{EPS} particulier, sans fontes, auquel sera associé un
429 fichier @file{EPS} qui, lui, contiendra toutes les pages (systèmes) et
430 les fontes. Notez qu'il s'agit du mode que @command{lilypond-book}
435 @tab Ne génère aucun fichier imprimable. Cette option est équivalente à
436 @code{-dno-print-pages}.
440 @tab Génère du@emph{Scalable Vector Graphics}. Cette option permet de
441 créer un fichier SVG par page, sans incorporation des fontes. Nous vous
442 recommandons d'installer les fontes Century Schoolbook comprises dans le
443 paquetage LilyPond afin d'obtenir le meilleur rendu possible. Sous UNIX,
444 il suffit de les recopier, à partir du répertoire
445 @file{/usr/share/lilypond/VERSION/fonts/otf/}, dans @file{~/.fonts/}.
446 Les fichiers @code{SVG} alors générés devraient être lisibles par votre
447 éditeur SVG habituel. L'option @code{svg-woff} -- voir ci-après --
448 permet d'utiliser les fontes woff avec le moteur SVG.
452 @tab Recopie littéralement les commandes Scheme internes de formatage.
454 @item @code{check-internal-types}
456 @tab Vérifie qu'à chaque propriété est bien affecté un type.
458 @item @code{clip-systems}
460 @tab Génère des typons à partir d'une partition.
464 @tab Détermine le préfixe des fichiers de données (lecture seule).
466 @item @code{debug-gc}
468 @tab Génère une copie brute de la mémoire, aux fins de débogage.
470 @item @code{debug-gc-assert-parsed-dead}
472 @tab Pour débogage de la mémoire : s'assure que toute référence à
473 des objets analysés est effacée. Il s'agit d'une option interne qui
474 est automatiquement activée par l'option @code{`-ddebug-gc'}.
476 @item @code{debug-lexer}
478 @tab Débogage de l'analyseur lexical @emph{flex}.
480 @item @code{debug-page-breaking-scoring}
482 @tab Purge les calculs des configurations de saut de page.
484 @item @code{debug-parser}
486 @tab Débogage de l'analyseur @emph{bison}.
488 @item @code{debug-property-callbacks}
490 @tab Débogage des chaînes de @emph{callback} cycliques.
492 @item @code{debug-skylines}
494 @tab Débogage des lignes d'horizon.
496 @item @code{delete-intermediate-files}
498 @tab Supprime les fichiers @code{.ps} inutiles crées lors de la
501 @item @code{dump-cpu-profile}
503 @tab Génère une copie brute des informations de timing (dépend du
506 @item @code{dump-profile}
508 @tab Génère une copie brute de la mémoire et des temps de traitement
511 @item @code{dump-signatures}
513 @tab Génère une copie des signatures de chaque système. Cette option
514 est utilisée pour les tests de régression.
516 @item @code{eps-box-padding}
518 @tab Décale le bord gauche du typon EPS d'une valeur donnée en
521 @item @code{gs-load-fonts}
523 @tab Charge les fontes grâce à Ghostscript.
525 @item @code{gs-load-lily-fonts}
527 @tab Limite les fontes chargées par Ghostscript aux seules fontes
532 @tab Travaille silencieusement, et redirige tout le verbiage dans un
537 @strong{Note à l'attention des utilisateurs de Windows :} toutes
538 les informations concernant le traitement apparaissent au fur et à
539 mesure dans l'interpréteur de commandes lorsque vous lancez le programme
540 @code{lilypond.exe}, à l'inverse de @w{@code{lilypond-windows.exe}} qui
541 vous renvoie simplement la main. L'option @option{-dgui} vous permettra
542 alors de rediriger ces informations dans un fichier journal.
544 @multitable @columnfractions .33 .16 .51
547 @tab Affiche cette aide.
549 @item @code{include-book-title-preview}
551 @tab Inclut les titres de l'ouvrage dans les images de prévisualisation.
553 @item @code{include-eps-fonts}
555 @tab Inclut les fontes dans chaque fichier EPS contenant un système.
557 @item @code{include-settings}
559 @tab Inclut un fichier contenant les réglages globaux. Ce fichier sera
560 inclus avant traitement de la partition.
562 @item @code{job-count}
564 @tab Traite plusieurs fichiers en parallèle, selon le nombre de
567 @item @code{log-file}
568 @tab @code{#f [fichier]}
569 @tab Fournir @code{TOTO} en second argument redirigera la sortie dans le
570 fichier journal @code{TOTO.log}.
572 @item @code{max-markup-depth}
574 @tab Profondeur maximale de l'arborescence de @emph{markups}. Si un
575 @emph{markup} était plus profond, part du principe qu'on aboutira pas,
576 émet un avertissement et renvoie alors un @emph{markup} vide.
578 @item @code{midi-extension}
580 @tab Détermine l'extension par défaut des fichiers MIDI, selon la chaîne
583 @item @code{music-strings-to-paths}
585 @tab Convertit les chaînes textuelles en chemins lorsque les glyphes
586 font partie d'une fonte musicale.
588 @cindex paper-size, ligne de commande
589 @item @code{paper-size}
591 @tab Détermine la taille par défaut du papier. Veillez à ne pas oublier
592 d'encadrer la valeur par des guillemets échappés (@code{\"}).
593 @c Match " in context-sensitive editors
595 @item @code{pixmap-format}
597 @tab Détermine le format de sortie en images pixélisées pour
600 @item @code{point-and-click}
602 @tab Ajoute les liens @qq{point & click} à la sortie PDF ou SVG. Voir
603 @ref{Pointer-cliquer}.
605 @cindex format de sortie, définition
606 @cindex preview, ligne de commande
609 @tab Génère une prévisualisation en plus de la sortie normale.
613 Cette option, disponible dans tous les formats de sortie imprimables --
614 @code{pdf}, @code{png}, @code{ps}, @code{eps} et @code{svg} -- génère
615 un fichier de la forme @code{monFichier.preview.extension} comprenant le
616 titrage et le premier système. S'il existe plusieurs sections
617 @code{\book}, @code{\bookpart}, ce fichier contiendra les titrage et
618 premier système de chacun des @code{\book}, @code{\bookpart} et
619 @code{\score}, dès lors que la variable @code{print-all-headers} du bloc
620 @code{\paper} est activée.
622 Pour l'éviter, utilisez conjointement l'une des options
623 @option{-dprint-pages} ou @option{-dno-print-pages} selon vos besoins.
625 @multitable @columnfractions .33 .16 .51
626 @item @code{print-pages}
628 @tab Génère l'intégralité des pages de la partition. L'option
629 @option{-dno-print-pages} est particulièrement utile lorsqu'utilisée
630 conjointement avec l'option @option{-dpreview}.
632 @item @code{profile-property-accesses}
634 @tab Enregistre des statistiques des appels à la fonction
635 @code{get_property()}.
637 @item @code{protected-scheme-parsing}
639 @tab Continue en dépit des erreurs que l'analyseur syntaxique
640 détecterait dans du code Scheme inclus. Lorsque basculé sur @code{#f},
641 stoppe le traitement s'il y a erreur et affiche une trace de la pile.
643 @item @code{read-file-list}
644 @tab @code{#f [fichier]}
645 @tab Spécifie un fichier listant les différents fichiers sources à
648 @item @code{relative-includes}
650 @tab Face à une instruction @code{\include}, recherche les fichiers à
651 inclure relativement à l'endroit où se trouve le fichier en cours de
652 traitement plutôt que par rapport au fichier maître.
654 @item @code{resolution}
656 @tab Détermine, en @code{dpi}, la résolution des pixmaps @code{PNG} à
657 générer selon la valeur donnée.
661 @tab Ne pas avoir une confiance aveugle dans le code @file{.ly}.
665 Lorsque LilyPond est accessible au travers d'un serveur web, il est
666 @strong{impératif} d'utiliser les options @option{--safe} ou
667 @option{--jail}. L'option @option{--safe} aura pour effet d'empêcher
668 tout code Scheme inclus de mettre en péril votre installation grâce à
669 quelque chose du style
673 #(s ystem "rm -rf /") % trop dangeureux à écrire sans faute
675 c4^$(ly:gulp-file "/etc/passwd") % malveillant mais pas destructeur
680 L'option @code{-dsafe} forcera l'évaluation, au fil de l'eau et par un
681 module sécurisé, des expressions Scheme contenues dans le fichier
682 source. Ce module sécuritaire, dérivé du module GUILE @file{safe-r5rs},
683 ajoute un certain nombre de fonctions -- listées dans
684 @file{scm/safe-lily.scm} -- à l'API de LilyPond.
686 De plus, le mode @emph{safe} ne permet ni l'utilisation de directives
687 @code{\include} ni le recours aux obliques inversées (@emph{backslash})
688 dans les chaînes @TeX{}. L'import de variables LilyPond dans du code
689 Scheme n'est pas possible en mode sécurisé.
691 L'option @code{-dsafe} @strong{ne détecte pas} l'utilisation abusive des
692 ressources. Il est donc possible que le programme finisse par rester
693 sans réponse si on lui envoie une boucle sans fin. C'est la raison pour
694 laquelle nous recommandons, lorsque LilyPond tourne sur un serveur
695 accessible au public, d'en limiter aussi bien les ressources processeur
698 Notez bien que l'utilisation du mode sécuritaire empêchera aussi la
699 compilation d'un certain nombre de fragments LilyPond. L'option
700 @code{--jail} est dans ce cas une excellente alternative en terme de
701 sécurité, même si elle requiert plus de temps à mettre en place -- voir
702 @ref{Options basiques de lilypond}.
704 @multitable @columnfractions .33 .16 .51
705 @item @code{separate-log-files}
707 @tab Pour les fichiers @code{FICHIER1.ly}, @code{FICHIER2.ly}, etc.
708 enregistre le déroulement dans les journaux @code{FICHIER1.log},
709 @code{FICHIER2.log}@dots{}
711 @item @code{show-available-fonts}
713 @tab Liste le nom des fontes disponibles.
715 @item @code{strict-infinity-checking}
717 @tab Force le crash en présence des points d'exception de virgule
718 flottante @code{Inf} ou @code{NaN} -- infini ou non-nombre.
720 @item @code{strip-output-dir}
722 @tab Supprime, lors du nommage des fichiers résultant, la partie
723 correspondant au répertoire des fichiers sources.
725 @item @code{strokeadjust}
727 @tab Force l'ajustement des traits PostScript. Cette option trouve
728 toute son utilité pour générer du PDF à partir de PostScript --
729 l'ajustement des traits est en principe automatiquement activé pour les
730 périphériques bitmap à faible résolution. Sans cette option, les
731 visionneurs de PDF ont tendance à ne pas rendre de manière constante
732 l'épaisseur des hampes dans les résolutions habituelles des écrans.
733 Bien que n'affectant pas notoirement la qualité d'impression, cette
734 option accroit notablement la taille des fichiers PDF.
736 @item @code{svg-woff}
738 @tab Utilise, avec le moteur SVG, les fontes @code{woff}.
740 @item @code{trace-memory-frequency}
742 @tab Enregistre l'utilisation de la cellule Scheme plusieurs fois par
743 seconde, dans les fichiers @code{FICHIER.stacks} et
744 @code{FICHIER.graph}.
746 @item @code{trace-scheme-coverage}
748 @tab Enregistre la couverture des fichiers Scheme dans @code{FILE.cov}.
752 @tab Passe en mode verbeux, ce qui correspond à un niveau de
753 journalisation @code{DEBUG} (lecture seule).
755 @item @code{warning-as-error}
757 @tab Considère tous les messages d'avertissement et « erreur de
758 programmation » comme étant de véritables erreurs.
762 @node Variables d'environnement
763 @unnumberedsubsec Variables d'environnement
764 @translationof Environment variables
767 @cindex LILYPOND_DATADIR
769 @command{lilypond} reconnaît les variables d'environnement
773 @item LILYPOND_DATADIR
774 Cette variable spécifie le répertoire où seront recherchés par défaut
775 les différentes versions des messages ainsi qu'un certain nombre de
776 fichiers nécessaires au traitement. Il devrait contenir les
777 sous-répertoires @file{ly/}, @file{ps/}, @file{tex/}, etc.
780 Cette variable détermine la langue dans laquelle seront émis les
783 @item LILYPOND_LOGLEVEL
784 Cette variable détermine le niveau par défaut de verbosité. En
785 l'absence de niveau explicite -- autrement dit la ligne de commande ne
786 comporte pas de @option{--loglevel} -- c'est cette valeur qui sera
789 @item LILYPOND_GC_YIELD
790 Cette variable permet d'ajuster l'empreinte mémoire et le rendement de
791 la machine. Il s'agit en fait d'un pourcentage d'allocation de
792 mémoire : lorsqu'il est élevé, le programme favorisera
793 l'utilisation de la mémoire ; une faible valeur consommera plus de
794 temps processeur. Par défaut, cette valeur est fixée à @code{70}.
799 @node Exécution de LilyPond en mode protégé
800 @unnumberedsubsec Exécution de LilyPond en mode protégé
801 @translationof LilyPond in chroot jail
803 Paramétrer un serveur afin qu'il puisse faire fonctionner LilyPond en
804 mode protégé sur un pseudo-périphérique est une tâche sensible. Les
805 différentes étapes à suivre sont répertoriées ci-dessous. Les exemples
806 qu'elle comportent proviennent d'une distribution GNU/Linux Ubuntu et
807 nécessiteront l'utilisation de @code{sudo} autant que de besoin.
811 @item Installation des paquetages nécessaires : LilyPond, Ghostscript et
814 @item Création de l'utilisateur @code{lily} :
821 Ceci, par la même occasion, créera un groupe spécifique pour
822 l'utilisateur @code{lily} ainsi que son répertoire personnel
825 @item Création, dans le répertoire personnel de l'utilisateur
826 @code{lily}, d'un espace agissant en tant que système de fichiers :
829 dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000
833 Cette commande a créé un fichier de 200 MB utilisable par le
834 @qq{système protégé}.
836 @item Création d'un pseudo-périphérique, génération d'un système de
837 fichiers et chargement de celui-ci, puis création d'un répertoire
838 accessible en écriture pour l'utilisateur @code{lily} :
842 losetup /dev/loop0 /home/lily/loopfile
843 mkfs -t ext3 /dev/loop0 200000
844 mount -t ext3 /dev/loop0 /mnt/lilyloop
845 mkdir /mnt/lilyloop/lilyhome
846 chown lily /mnt/lilyloop/lilyhome
849 @item Affectation, au niveau configuration du serveur, de
850 @code{/mnt/lilyloop} en tant que JAIL et @code{/lilyhome} en tant que
853 @item Création d'une arborescence, dans l'espace protégé, et recopie de
854 tous les fichiers nécessaires -- voir le script plus loin.
856 Le recours à l'utilitaire @code{sed} permet de créer les commandes de
857 copie de tout ce qui est nécessaire à un exécutable :
860 for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/; \
861 do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& \
862 cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \
863 \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done
868 @subheading Exemple de script fonctionnel en 32-bit sur Ubuntu 8.04
872 ## les réglages par défaut
876 loopdevice=/dev/loop0
877 jaildir=/mnt/lilyloop
878 # le préfixe (sans slash au début !)
880 # le répertoire du système où lilypond est installé
881 lilydir=/$lilyprefix/lilypond/
883 userhome=$home/$username
884 loopfile=$userhome/loopfile
886 dd if=/dev/zero of=$loopfile bs=1k count=200000
888 losetup $loopdevice $loopfile
889 mkfs -t ext3 $loopdevice 200000
890 mount -t ext3 $loopdevice $jaildir
891 mkdir $jaildir/lilyhome
892 chown $username $jaildir/lilyhome
895 mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp
898 cp -r -L $lilydir $lilyprefix
899 cp -L /bin/sh /bin/rm bin
900 cp -L /usr/bin/convert /usr/bin/gs usr/bin
901 cp -L /usr/share/fonts/truetype usr/share/fonts
903 # la formule magique de recopie des bibliothèques
904 for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh" \
905 "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=> \
906 \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed \
907 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' \
908 | sed '/.*=>.*/d'; done | sh -s
910 # les fichiers partagés pour ghostscript...
911 cp -L -r /usr/share/ghostscript usr/share
912 # les fichiers partagés pour ImageMagick
913 cp -L -r /usr/lib/ImageMagick* usr/lib
915 ### Partant du principe que test.ly est dans /mnt/lilyloop/lilyhome,
916 ### on devrait pouvoir lancer :
917 ### Attention : /$lilyprefix/bin/lilypond est un script qui
918 ### définit LD_LIBRARY_PATH - c'est primordial
919 /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly
923 @node Messages d'erreur
924 @section Messages d'erreur
925 @translationof Error messages
927 @cindex erreur, messages
929 Différents messages d'erreur sont susceptibles d'apparaître au cours de
930 la compilation d'un fichier :
934 @item Warning -- Avertissement
936 @cindex avertissement
937 Ce type de message est émis lorsque LilyPond détecte quelque chose de
938 suspect. Si vous avez demandé quelque chose qui sort de l'ordinaire,
939 vous saurez probablement ce à quoi il est fait référence et ignorerez de
940 tels messages sans remord. Néanmoins, les messages d'avertissement
941 indiquent la plupart du temps une incohérence dans le fichier source.
943 @item Error -- Erreur
945 LilyPond a détecté une erreur. L'étape en cours, qu'il s'agisse de
946 l'analyse, de l'interprétation des données ou bien du formatage, sera
947 menée à son terme, puis LilyPond s'arrêtera.
949 @item Fatal error -- Erreur fatale
951 LilyPond est confronté à une anomalie bloquante. Ceci ne se produit que
952 très rarement, et la plupart du temps en raison d'une installation
953 défectueuse des fontes.
955 @item Scheme error -- Erreur Scheme
956 @cindex trace, Scheme
959 Les erreurs qui interviennent lors de l'exécution de code Scheme sont
960 gérées par l'interpréteur Scheme. L'utilisation du mode verbeux
961 (options @option{-V} ou @option{--verbose}) vous permettra de localiser
962 l'appel de fonction délictueux.
964 @item Programming error -- Erreur de programmation
965 @cindex Programming error
966 @cindex Erreur de programmation
967 LilyPond est confronté à une incohérence interne. Ce type de message
968 est destiné à venir en aide aux développeurs et débogueurs. En règle
969 générale, vous pouvez tout simplement les ignorer. Parfois, il y en a
970 tant qu'ils masquent ce qui pourrait vous intéresser@dots{}
972 @item Aborted (core dumped) -- Abandon
973 @cindex Aborted (core dumped)
974 Ce type de message indique que LilyPond a planté en raison d'une grave
975 erreur de programmation. La survenance d'un tel message est considérée
976 comme de la plus haute importance. Si vous y étiez confronté,
977 transmettez un rapport de bogue.
980 @cindex errors, message format
981 Lorsque l'avertissement ou l'erreur est directement lié au fichier
982 source, le message est libellé sous la forme
985 @var{fichier}:@var{ligne}:@var{colonne}: @var{message}
986 @var{contenu de la ligne litigieuse}
989 Un saut de ligne est placé dans la ligne de code, indiquant l'endroit
990 précis du problème, comme ici :
993 test.ly:2:19: erreur: n'est pas une durée: 5
998 Notez que ces coordonnées constituent l'approximation au mieux par
999 LilyPond dans le code ayant déclenché l'avertissement ou l'erreur. En
1000 règle générale, erreurs et avertissements surviennent lorsque LilyPond
1001 rencontre quelque chose d'inattendu. Lorsque la ligne indiquée ne vous
1002 semble pas comporter d'élément litigieux, remontez de quelques lignes
1005 Par ailleurs, des diagnostics peuvent être déclenchés à n'importe quel
1006 moment au cours des différentes étapes du traitement. Par exemple,
1007 lorsque certaines parties de la source sont traitées plusieurs fois --
1008 sortie MIDI et sortie imprimable -- ou qu'une même variable musicale est
1009 utilisée dans plusieurs contextes, peut apparaître le même message à
1010 plusieurs reprises. Les diagnostics effectués à une étape avancée du
1011 traitement, tels que les contrôles de mesure, sont aussi susceptibles
1012 d'apparaître plusieurs fois.
1014 Vous trouverez d'autres informations sur les erreurs au chapitre
1015 @ref{Quelques erreurs des plus courantes}.
1018 @node Quelques erreurs des plus courantes
1019 @section Quelques erreurs des plus courantes
1020 @translationof Common errors
1022 Les conditions amenant aux erreurs qui suivent sont fréquentes, bien
1023 qu'elles ne soient pas évidentes ni facilement localisables. Nous
1024 espérons que ces explications vous aideront à les résoudre plus
1028 * La musique déborde de la page::
1029 * Apparition d'une portée supplémentaire::
1030 * Message d'erreur Unbound variable %::
1031 * Message d'erreur FT_Get_Glyph_Name::
1032 * staff-affinities devraient aller en ordre décroissant::
1033 * Message d'erreur unexpected new::
1037 @node La musique déborde de la page
1038 @unnumberedsubsec La musique déborde de la page
1039 @translationof Music runs off the page
1041 Lorsque la musique s'épanche au delà de la marge droite ou bien semble
1042 anormalement comprimée, la raison en est le plus souvent une note à la
1043 durée erronée ; cela finit par provoquer le débordement de la
1044 dernière note d'une mesure. Rien ne s'oppose à ce que la dernière note
1045 d'une mesure ne s'arrête avant la barre de mesure ; on considère
1046 simplement qu'elle se prolonge sur la mesure suivante. Des débordements
1047 à répétition finissent par générer une musique comprimée ou qui sort de
1048 la page, pour la simple et bonne raison que les sauts de ligne
1049 automatiques ne peuvent intervenir qu'à la fin d'une mesure complète,
1050 autrement dit lorsque toutes les notes sont terminées avant la fin de la
1053 @warning{Une durée erronée peut empêcher les sauts de ligne, ce qui
1054 conduit à une musique compressée, voire à un débordement de la page.}
1056 Une erreur de durée sera bien plus facilement localisable si vous
1057 positionnez régulièrement des contrôles de barre de mesure -- voir
1058 @ruser{Vérification des limites et numéros de mesure}.
1060 Si vous tenez absolument à enchaîner de tels débordements, vous devrez
1061 insérer des barres de mesure invisibles là où vous souhaitez positionner
1062 un saut de ligne. Consultez le chapitre @ruser{Barres de mesure} pour
1066 @node Apparition d'une portée supplémentaire
1067 @unnumberedsubsec Apparition d'une portée supplémentaire
1068 @translationof An extra staff appears
1070 Lorsque les contextes ne sont pas créés explicitement par la commande
1071 @code{\new}, ils le seront si la commande à exécuter n'est pas censée
1072 s'appliquer au contexte en cours. Pour des partitions simples, le fait
1073 que les contextes soient automatiquement créés rend bien des services,
1074 et c'est d'ailleurs le cas pour la majorité des exemples contenus dans
1075 les manuels de LilyPond. Cependant, la création implicite d'un contexte
1076 peut aboutir à l'apparition d'une portée @qq{parasite}. On s'attend par
1077 exemple, en lisant le code qui suit, à ce que toutes les têtes de note
1078 soient en rouge, alors que le résultat nous présente deux portées et que
1079 les notes, placées sur la portée inférieure, restent en noir.
1081 @lilypond[quote,verbatim,relative=2]
1082 \override Staff.NoteHead.color = #red
1086 Étant donné qu'aucun contexte @code{Staff} n'existe lorsque la
1087 dérogation est introduite, LilyPond le crée implicitement pour lui
1088 appliquer la directive considérée. Survient alors la commande
1089 @code{\new Staff} qui, à son tour, crée une nouvelle portée pour
1090 contenir les notes qui suivent. Voici la syntaxe correcte pour obtenir
1091 ces notes en rouge :
1093 @lilypond[quote,verbatim,relative=2]
1095 \override Staff.NoteHead.color = #red
1101 @node Message d'erreur Unbound variable %
1102 @unnumberedsubsec Message d'erreur @code{Unbound variable %}
1103 @translationof Error message Unbound variable %
1105 Ce message d'erreur, qu'il apparaisse sur le terminal ou en fin de
1106 fichier journal, est associé à un message du type @qq{GUILE a signalé
1107 une erreur@dots{}}. Il survient à chaque fois qu'un commentaire
1108 @emph{LilyPond} est indûment placé dans une routine @emph{Scheme}.
1110 Un commentaire LilyPond est introduit par le signe pourcent (@code{%})
1111 et ne doit en aucun cas se trouver dans une routine Scheme. En Scheme,
1112 les commentaires s'introduisent par un point-virgule (@code{;}).
1115 @node Message d'erreur FT_Get_Glyph_Name
1116 @unnumberedsubsec Message d'erreur @code{FT_Get_Glyph_Name}
1117 @translationof Error message FT_Get_Glyph_Name
1119 Ce message d'erreur, qu'il apparaisse sur le terminal ou en fin de
1120 fichier journal, survient lorsqu'un fichier source contient des
1121 caractères non ASCII et qu'il n'a pas été enregistré avec un encodage
1122 UTF-8. Pour plus de détails, reportez-vous au chapitre
1123 @ruser{Caractères spéciaux}.
1126 @node staff-affinities devraient aller en ordre décroissant
1127 @unnumberedsubsec @emph{staff-affinities} devraient aller en ordre décroissant
1128 @translationof Warning staff affinities should only decrease
1130 Cet avertissement est émis lorsque la partition ne comporte pas de
1131 portée, comme par exemple une feuille de chant avec un contexte
1132 @code{ChordName} et un contexte @code{Lyrics}. Ce message disparaîtra
1133 dès lors que vous autoriserez l'un de ces contextes à se comporter comme
1134 une portée, à l'aide de l'instruction
1137 \override VerticalAxisGroup.staff-affinity = ##f
1141 que vous insérerez dès sa création. Pour plus d'information,
1142 reportez-vous à la rubrique
1143 @ruser{Espacement des lignes rattachées à des portées}.
1146 @node Message d'erreur unexpected new
1147 @unnumberedsubsec Message d'erreur unexpected @code{@bs{}new}
1148 @translationof Error message unexpected new
1150 Un bloc @code{\score} ne peut contenir qu'@strong{une seule} expression
1151 musicale. Si, par contre, il comporte plusieurs @code{\new Staff},
1152 @code{\new StaffGroup} ou autres contextes introduits par une commande
1153 @code{\new} qui ne seraient pas bornés par des accolades
1154 @code{@{ @dots{} @}} ou des doubles chevrons @code{<< @dots{} >>} comme
1159 % Invalide ! Génère l'erreur : syntax error, unexpected \new
1160 % en français : erreur de syntaxe : \new inattendu
1161 \new Staff @{ @dots{} @}
1162 \new Staff @{ @dots{} @}
1167 vous obtiendrez ce message d'erreur.
1169 Cette erreur sera évitée dès lors que toutes les instances de
1170 @code{\new} sont bornées par des accolades ou des doubles chevrons.
1172 Des accolades placeront ces clauses @code{\new} en séquence :
1174 @lilypond[quote,verbatim]
1177 \new Staff { a' a' a' a' }
1178 \new Staff { g' g' g' g' }
1184 alors que des doubles chevrons les placeront en parallèle ; autrement
1185 dit, LilyPond les traitera simultanément :
1187 @lilypond[quote,verbatim]
1190 \new Staff { a' a' a' a' }
1191 \new Staff { g' g' g' g' }