@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
-
@ignore
- Translation of GIT committish: 4a527608c5ff2ce31e596495d00dce181dc1b9ea
+ Translation of GIT committish: c610645cc9a77cba1a2798280965db142d649ac5
When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
+ version that you are working on. For details, see the Contributors'
+ Guide, node Updating translation committishes..
@end ignore
+@c \version "2.16.0"
-@node Exécution de LilyPond
-@chapter Exécution de LilyPond
-@translationof Running LilyPond
+@c Translators: Jean-Charles Malahieude
+@c Translation checkers:
-@untranslated
+@node Exécution de lilypond
+@chapter Exécution de @command{lilypond}
+@translationof Running lilyPond
+Ce chapitre passe en revue ce qui se passe lorsque vous lancez LilyPond.
@menu
* Utilisation habituelle::
* Utilisation en ligne de commande::
* Messages d'erreur::
-* Mise à jour des fichiers avec convert-ly::
-* Rapport de bogue::
+* Quelques erreurs des plus courantes::
@end menu
@node Utilisation habituelle
@section Utilisation habituelle
@translationof Normal usage
-@untranslated
+La plupart des utilisateurs de LilyPond le font au travers d'une
+interface graphique (@emph{GUI} pour @emph{graphical user interface}).
+Si vous ne l'avez pas encore parcouru, lisez le @rlearning{Tutoriel}.
+Si vous utilisez un éditeur alternatif pour rédiger vos fichiers
+LilyPond, référez-vous à la documentation de celui-ci.
@node Utilisation en ligne de commande
@section Utilisation en ligne de commande
@translationof Command-line usage
-@untranslated
+Nous nous intéresserons ici aux spécificités de LilyPond employé en
+ligne de commande. La ligne de commande permet de faire appel à
+certaines options particulières. D'autre part, certains utilitaires
+associés, tel que @code{midi2ly}, ne sont disponibles qu'en ligne de
+commande.
+
+Par @qq{ligne de commande}, nous entendons l'interface de commande du
+système. Les utilisateurs de Windows seront certainement plus familiers
+des termes @qq{fenêtre DOS} ou @qq{invite de commande}. Quant aux
+utilisateurs de MacOS@tie{}X, ils connaissent assurément les termes
+@qq{console} et @qq{terminal}. Les paramétrages spécifiques au système
+MacOS font l'objet d'un @rwebnamed{MacOS X,chapitre particulier}.
+
+Notre propos n'est pas ici d'expliquer ce qu'est l'interface de
+commande pour un système informatique ni comment elle fonctionne.
+Aussi, si vous ne savez de quoi il retourne, nous vous renvoyons aux
+nombreuses documentations que vous pourrez trouver sur ce sujet.
@menu
* Lancement de lilypond::
-* Options en ligne de commande::
+* Options basiques de lilypond::
+* Options avancées de lilypond::
* Variables d'environnement::
+* Exécution de LilyPond en mode protégé::
@end menu
@node Lancement de lilypond
-@subsection Lancement de lilypond
+@unnumberedsubsec Lancement de @command{lilypond}
@translationof Invoking lilypond
-@untranslated
+L'exécutable @command{lilypond} en ligne de commande se lance
+ainsi@tie{}:
+
+@example
+lilypond [@var{option}]@dots{} @var{fichier}@dots{}
+@end example
+
+Lorsque le fichier est fourni sans extension, LilyPond présume qu'il
+s'agit de @file{.ly}. Pour interpréter directement l'entrée standard
+(@emph{stdin}), fournissez un tiret (@code{-}) en lieu et place de
+@var{fichier}.
+
+Le traitement de @file{monfichier.ly} produira @file{monfichier.ps} et
+@file{monfichier.pdf}. Vous pouvez spécifier plusieurs fichiers à la
+fois@tie{}; ils seront traités indépendamment les uns des
+autres.@footnote{Le statut de GUILE n'étant pas réinitialisé après
+traitement d'un fichier @file{.ly}, veillez à ne pas modifier les
+réglages par défaut du système à partir d'assertions en Scheme.}
+
+Lorsque @file{monfichier.ly} contient plus d'une section @code{\book},
+les fichiers produits -- à partir du deuxième -- seront numérotés. Par
+ailleurs, la valeur affectée à @code{output-suffix} sera insérée entre la
+racine et le numéro. Par exemple, un fichier @var{racine} qui
+contiendrait
+
+@example
+#(define output-suffix "violon")
+\score @{ @dots{} @}
+#(define output-suffix "cello")
+\score @{ @dots{} @}
+@end example
+
+@noindent
+fournira grâce à LilyPond @file{@var{racine}-violon.pdf} et
+@file{@var{racine}-cello-1.pdf}.
+
+
+@unnumberedsubsubsec Commandes standard de l'interpréteur
+@translationof Standard shell commands
+
+Si votre interpréteur -- terminal, console, etc. -- prend en charge les
+redirections, les commandes qui suivent vous permettront de
+judicieusement rediriger les affichages de la console dans un
+fichier@tie{}:
+
+@itemize
+
+@item
+@code{lilypond fichier.ly 1>stdout.log} pour le verbiage normal
+
+@item
+@code{lilypond fichier.ly 2>stderr.log} pour les messages d'erreur
+
+@item
+@code{lilypond fichier.ly &>tous.log} pour garder une trace de tout ce
+qui s'est passé
+
+@end itemize
+
+Consultez avant tout la documentation de votre interpréteur habituel
+pour vérifier qu'il prend en charge ces options dans cette syntaxe.
+Notez bien qu'il s'agit ici de commandes internes à l'interpréteur et
+qui n'ont rien à voir avec LilyPond.
+
+
+@node Options basiques de lilypond
+@unnumberedsubsec Options basiques de @command{lilypond}
+@translationof Basic command line options for LilyPond
+
+@cindex lancement de @command{lilypond}
+@cindex ligne de commande, options pour @command{lilypond}
+@cindex options, ligne de commande
+@cindex switches
+@cindex commutateurs
+
+Différentes options sont disponibles en ligne de commande@tie{}:
+
+@table @code
+
+@item -d,--define-default=@var{variable}=@var{valeur}
+Voir @ref{Options avancées de lilypond}.
+
+@cindex Scheme, évaluation d'expression
+@cindex expression Scheme, évaluation
+@item -e,--evaluate=@var{expr}
+Évalue l'expression Scheme @var{expr} avant d'analyser tout fichier
+@file{.ly}. Lorsque vous spécifiez l'option @option{-e} à plusieurs
+reprises, l'évaluation sera faite en séquence.
+
+Dans la mesure où l'expression est évaluée par le module
+@code{guile-user}, vous devrez, dès lors que @var{expr} utilise des
+définitions, spécifier
+
+@example
+lilypond -e '(define-public a 42)'
+@end example
+
+@noindent
+en ligne de commande, et ajouter la ligne
+
+@example
+#(use-modules (guile-user))
+@end example
+
+@noindent
+en tête de votre fichier @file{.ly}.
+
+@warning{Les utilisateurs de Windows doivent utiliser des guillemets
+doubles @code{"} en lieu et place des guillemets simples @code{'}.}
+@c Match " in context-sensitive editors
+
+@cindex sortie, format
+@cindex format de sortie
+@item -f,--format=@var{format}
+Détermine le format à produire. Il peut s'agir de @code{ps}, @code{pdf}
+ou @code{png}.
+
+Exemple : @code{lilypond -fpng @var{monfichier}.ly}
+
+@item -h,--help
+Affiche un résumé des commandes.
+
+@item -H,--header=@var{CHAMP}
+Recopie le champ d'entête dans le fichier @file{RACINE.@var{CHAMP}}.
+
+@item -i,--init=@var{fichier}
+Définit @var{fichier} (par défaut @file{init.ly}) en tant que fichier
+d'initialisation.
+
+@cindex recherche de fichier
+@cindex chemin de recherche
+@item -I,--include=@var{répertoire}
+Ajoute @var{répertoire} au chemin de recherche pour les inclusions.
+
+Vous pouvez mentionner plusieurs fois l'option @option{-I}, auquel cas
+la recherche commencera dans le premier répertoire inclus et, si le
+fichier en question ne s'y trouve pas, les répertoires suivants seront
+examinés l'un après l'autre.
+
+@cindex chroot jail, fonctionnement
+@item -j,--jail=@var{user},@var{group},@var{jail},@var{dir}
+Lance @command{lilypond} dans un environnement protégé.
+
+L'option @option{--jail} est une alternative qui offre plus de
+flexibilité que l'option @option{--safe} lorsque LilyPond est installé
+sur un serveur web ou traite des fichiers externes -- voir
+@ref{Options avancées de lilypond}.
+
+L'option @option{--jail} va détourner la racine de @command{lilypond}
+sur @var{jail} juste avant d'effectuer la compilation à proprement
+parler. L'utilisateur et le groupe sont modifiés en conséquence, et le
+répertoire en cours devient @var{dir}. Ces réglages assurent -- du
+moins en théorie -- l'impossibilité de s'échapper de la cellule. Notez
+cependant que, pour que l'option @option{--jail} soit fonctionnelle,
+@command{lilypond} doit être lancé en tant qu'administrateur -- ce qui
+se réalise aisément à l'aide de la commande @command{sudo}.
+
+La création d'un environnement sécurisé requiert quelques précautions
+dans la mesure où LilyPond doit disposer de tout ce dont il a besoin
+pour compiler le fichier source @strong{à l'intérieur de la cellule}.
+L'ermitage, avant d'être viable, requiert donc les étapes
+suivantes@tie{}:
+
+@table @asis
+
+@item Création d'un système de fichiers indépendant
+L'intérêt d'un système de fichiers dédié à LilyPond réside dans le fait
+qu'on peut le brider à l'aide des options @code{noexec}, @code{nodev} et
+@code{nosuid}. Il sera de fait impossible de lancer des exécutables ou
+d'écrire sur un périphérique à partir de LilyPond. Si vous n'avez pas
+l'intention de créer un tel système sur une partition séparée, vous
+pouvez avoir recours à un pseudo-périphérique (@emph{loop device}) monté
+à partir d'un simple fichier de taille raisonnable. D'autre part, le
+recours à un système de fichiers indépendant permet de limiter l'espace
+dévolu à LilyPond.
+
+@item Création d'un utilisateur spécifique
+L'utilisation de LilyPond au sein de la cellule devrait être réservé à
+un utilisateur aux droits restreints. Il faudra donc créer un
+utilisateur et un groupe spécifiques -- disons
+@w{@code{lily}/@code{lily}} -- qui n'aura accès en écriture qu'à un
+unique répertoire déterminé par la valeur de @var{dir}.
+
+@item Agencement des lieux
+LilyPond a besoin d'un certain nombre de fichiers pour pouvoir tourner
+correctement. Ces fichiers devront donc tous se retrouver dans
+l'environnement protégé, distribués selon la même arborescence que dans
+le système d'origine. Ainsi l'intégralité de l'installation de LilyPond
+(en principe @file{/usr/share/lilypond}) doit y être dupliquée.
+
+En cas de problème, lancer LilyPond en utilisant @command{strace}
+devrait vous permettre de déterminer quels fichiers manquent à l'appel.
+
+@item Lancement de LilyPond
+Dans un environnement protégé monté avec l'option @code{noexec}, il
+est impossible de lancer un quelconque programme extérieur. LilyPond ne
+saurait donc avoir recours à un moteur de traitement qui le mettrait
+dans cette situation. Comme nous l'avons vu plus haut, LilyPond sera
+lancé avec les privilèges de l'administrateur -- privilèges qu'il perdra
+aussitôt --, ce qui peut nécessiter le recours à la commande
+@code{sudo}. Il est par ailleurs judicieux de limiter le temps
+processeur alloué à LilyPond -- grâce à @command{ulimit@tie{}-t} par
+exemple -- ainsi que, si votre système le permet, la taille de la
+mémoire. Voir aussi @ref{Exécution de LilyPond en mode protégé}.
+@end table
+
+@cindex loglevel
+@cindex verbosité, définir le degré de
+@item -l,--loglevel=@var{DEGRÉ}
+Règle le niveau de verbosité des messages console à @var{DEGRÉ}. Les
+différentes valeurs sont@tie{}:
+
+@table @code
+@item NONE
+Aucun verbiage, même pas les messages d'erreur.
+
+@item ERROR
+Uniquement les messages d'erreur@tie{}; pas de message d'avertissement
+ni de progression.
+
+@item WARN
+Messages d'avertissement ou d'erreur@tie{}; pas d'information de
+progression.
+
+@item BASIC_PROGRESS
+Information de progression basique (réussite) et avertissements ou erreurs.
+
+@item PROGRESS
+Toutes les informations de progression, avertissements et erreurs.
+
+@item INFO (par défaut)
+Informations de progression, avertissements et erreurs, ainsi que
+d'autres informations quant à l'exécution.
+
+@item DEBUG
+Tout ce qui peut être affiché, y compris le verbiage utile au débogage.
+
+@end table
+
+@cindex redirection
+@cindex répertoire de destination
+@cindex fichier de destination
+@item -o,--output=@var{FICHIER} ou @var{RÉPERTOIRE}
+Détermine le nom par défaut du fichier résultant à @var{FICHIER}@tie{};
+lorsque l'argument @var{RÉPERTOIRE} correspond à un répertoire déjà
+existant, c'est là que les fichiers résultants seront déposés. Le
+suffixe adéquat sera ajouté (par ex. @code{.pdf} pour du pdf) dans tous
+les cas.
+
+@cindex PostScript, output
+@cindex PS (PostScript), output
+@item --ps
+Génère du PostScript.
+
+@cindex Portable Network Graphics (PNG), output
+@cindex PNG (Portable Network Graphics), output
+@item --png
+Génère une image par page, au format PNG@tie{}; ceci sous-entend
+l'utilisation de @option{--ps}. La résolution de l'image, en DPI, peut
+se régler en ajoutant par exemple
+@example
+-dresolution=110
+@end example
+
+@cindex Portable Document Format (PDF), output
+@cindex PDF (Portable Document Format), output
+@item --pdf
+Génère du PDF. Ceci sous-entend l'utilisation de @option{--ps}.
+
+@item -v,--version
+Affiche le numéro de version.
+
+@item -V,--verbose
+Active le mode verbeux@tie{}: affichage de l'intégralité du chemin
+d'accès de chaque fichier, et information des temps de traitement.
+
+@item -w,--warranty
+Affiche les informations de garantie applicables à GNU LilyPond -- il
+est livré @strong{SANS GARANTIE}@tie{}!
+
+@end table
+
+
+@node Options avancées de lilypond
+@unnumberedsubsec Options avancées de @command{lilypond}
+@translationof Advanced command line options for LilyPond
+
+@table @code
+
+@item -d@var{[nom-option]}=@var{[valeur]},--define-default=@var{[nom-option]}=@var{[valeur]}
+Affecte la valeur Scheme @var{valeur} à l'option interne @var{nom-option} du
+programme. En l'absence de @var{valeur}, le programme utilisera @var{#t}.
+Préfixer @var{nom-option} d'un @code{no-} vous permet de désactiver une option.
+Ainsi,
+
+@cindex point and click, ligne de commande
+@cindex pointer-cliquer, ligne de commande
+
+@example
+-dno-point-and-click
+@end example
+
+@noindent
+revient au même que
+@example
+-dpoint-and-click=#f
+@end example
+@end table
+
+@noindent Voici les différentes options disponibles, ainsi que leur
+valeur par défaut.
+
+@multitable @columnfractions .33 .16 .51
+@item @strong{Symbole}
+@tab @strong{Valeur}
+@tab @strong{Observations}
+
+
+@item @code{anti-alias-factor}
+@tab @code{1}
+@tab Adopte une résolution supérieure (selon le facteur donné),puis
+réduit au niveau du résultat afin d'éviter les @qq{distorsions} des
+images @code{PNG}.
+
+@item @code{aux-files}
+@tab @code{#t}
+@tab Génère les fichiers @code{.tex}, @code{.texi} et @code{.count}
+pour le moteur de rendu @code{EPS}.
+
+@item @code{backend}
+@tab @code{'ps}
+@tab Détermine le format de sortie à utiliser par le moteur de
+traitement. Les fichiers PostScript (format par défaut) incluent les
+fontes @code{TTF}, @code{Type1} et @code{OTF}, et aucune substitution ne
+sera opérée pour ces fontes. Si vous utilisez des jeux de caractères
+orientaux, le fichier aura vite fait d'atteindre une taille conséquente.
+
+@item
+@tab @code{'eps}
+@tab Génère du PostScript encapsulé. Chaque page (système) fera l'objet
+d'un fichier @file{EPS} particulier, sans fontes, auquel sera associé un
+fichier @file{EPS} qui, lui, contiendra toutes les pages (systèmes) et
+les fontes. Notez qu'il s'agit du mode que @command{lilypond-book}
+utilise par défaut.
+
+@item
+@tab @code{'null}
+@tab Ne génère aucun fichier imprimable. Cette option est équivalente à
+@code{-dno-print-pages}.
+
+@item
+@tab @code{'svg}
+@tab Génère du@emph{Scalable Vector Graphics}. Cette option permet de
+créer un fichier @code{SVG} par page, sans incorporation des fontes.
+Nous vous recommandons d'installer les fontes Century Schoolbook
+comprises dans le paquetage LilyPond afin d'obtenir le meilleur rendu
+possible. Sous UNIX, il suffit de les recopier, à partir du répertoire
+@file{/usr/share/lilypond/VERSION/fonts/otf/}, dans @file{~/.fonts/}.
+Les fichiers @code{SVG} alors générés devraient être lisibles par votre
+éditeur SVG habituel. L'option @code{svg-woff} -- voir ci-après --
+permet d'utiliser les fontes @code{woff} avec le moteur @code{SVG}.
+
+@item
+@tab @code{'scm}
+@tab Recopie littéralement les commandes Scheme internes de formatage.
+
+@item @code{check-internal-types}
+@tab @code{#f}
+@tab Vérifie qu'à chaque propriété est bien affecté un type.
+
+@item @code{clip-systems}
+@tab @code{#f}
+@tab Génère des typons à partir d'une partition.
+
+@item @code{datadir}
+@tab
+@tab Détermine le préfixe des fichiers de données (lecture seule).
+
+@item @code{debug-gc}
+@tab @code{#f}
+@tab Génère une copie brute de la mémoire, aux fins de débogage.
+
+@item @code{debug-gc-assert-parsed-dead}
+@tab @code{#f}
+@tab Pour débogage de la mémoire@tie{}: s'assure que toute référence à
+des objets analysés est effacée. Il s'agit d'une option interne qui
+est automatiquement activée par l'option @code{`-ddebug-gc'}.
+
+@item @code{debug-lexer}
+@tab @code{#f}
+@tab Débogage de l'analyseur lexical @emph{flex}.
+
+@item @code{debug-page-breaking-scoring}
+@tab @code{#f}
+@tab Purge les calculs des configurations de saut de page.
+
+@item @code{debug-parser}
+@tab @code{#f}
+@tab Débogage de l'analyseur @emph{bison}.
+
+@item @code{debug-property-callbacks}
+@tab @code{#f}
+@tab Débogage des chaînes de @emph{callback} cycliques.
+
+@item @code{debug-skylines}
+@tab @code{#f}
+@tab Débogage des lignes d'horizon.
+
+@item @code{delete-intermediate-files}
+@tab @code{#t}
+@tab Supprime les fichiers @code{.ps} inutiles crées lors de la
+compilation.
+
+@item @code{dump-cpu-profile}
+@tab @code{#f}
+@tab Génère une copie brute des informations de timing (dépend du
+système).
+
+@item @code{dump-profile}
+@tab @code{#f}
+@tab Génère une copie brute de la mémoire et des temps de traitement
+pour chaque fichier.
+
+@item @code{dump-signatures}
+@tab @code{#f}
+@tab Génère une copie des signatures de chaque système. Cette option
+est utilisée pour les tests de régression.
+
+@item @code{eps-box-padding}
+@tab @code{#f}
+@tab Décale le bord gauche du typon EPS d'une valeur donnée en
+millimètres.
+
+@item @code{gs-load-fonts}
+@tab @code{#f}
+@tab Charge les fontes grâce à Ghostscript.
+
+@item @code{gs-load-lily-fonts}
+@tab @code{#f}
+@tab Limites les fontes chargées par Ghostscript aux seules fontes
+LilyPond.
+
+@item @code{gui}
+@tab @code{#f}
+@tab Travaille silencieusement, et redirige tout le verbiage dans un
+fichier journal.
+@end multitable
+
+@noindent
+@strong{Note à l'attention des utilisateurs de Windows@tie{}:} toutes
+les informations concernant le traitement apparaissent au fur et à
+mesure dans l'interpréteur de commandes lorsque vous lancez le programme
+@code{lilypond.exe}, à l'inverse de @w{@code{lilypond-windows.exe}} qui
+vous renvoie simplement la main. L'option @option{-dgui} vous permettra
+alors de rediriger ces informations dans un fichier journal.
+
+@multitable @columnfractions .33 .16 .51
+@item @code{help}
+@tab @code{#f}
+@tab Affiche cette aide.
+
+@item @code{include-book-title-preview}
+@tab @code{#t}
+@tab Inclut les titres de l'ouvrage dans les images de prévisualisation.
+
+@item @code{include-eps-fonts}
+@tab @code{#t}
+@tab Inclut les fontes dans chaque fichier EPS contenant un système.
+@item @code{include-settings}
+@tab @code{#f}
+@tab Inclut un fichier contenant les réglages globaux. Ce fichier sera
+inclus avant traitement de la partition.
-@node Options en ligne de commande
-@subsection Options en ligne de commande
-@translationof Command line options
+@item @code{job-count}
+@tab @code{#f}
+@tab Traite plusieurs fichiers en parallèle, selon le nombre de
+@emph{jobs}.
-@untranslated
+@item @code{log-file}
+@tab @code{#f [fichier]}
+@tab Fournir @code{TOTO} en second argument redirigera la sortie dans le
+fichier journal @code{TOTO.log}.
+
+@item @code{max-markup-depth}
+@tab @code{1024}
+@tab Profondeur maximale de l'arborescence de @emph{markups}. Si un
+@emph{markup} était plus profond, part du principe qu'on aboutira pas,
+émet un avertissement et renvoie alors un @emph{markup} vide.
+
+@item @code{midi-extension}
+@tab @code{"midi"}
+@tab Détermine l'extension par défaut des fichiers MIDI, selon la chaîne
+donnée en argument.
+
+@item @code{music-strings-to-paths}
+@tab @code{#f}
+@tab Convertit les chaînes textuelles en chemins lorsque les glyphes
+font partie d'une fonte musicale.
+
+@item @code{old-relative}
+@tab @code{#f}
+@tab Affecte au mode @code{\relative} le même comportement pour de la
+musique simultanée que celui d'une syntaxe d'accords.
+
+@cindex paper-size, ligne de commande
+@item @code{paper-size}
+@tab @code{\"a4\"}
+@tab Détermine la taille par défaut du papier. Veillez à ne pas oublier
+d'encadrer la valeur par des guillemets échappés (@code{\"}).
+@c Match " in context-sensitive editors
+
+@item @code{pixmap-format}
+@tab @code{png16m}
+@tab Détermine le format de sortie en images pixélisées pour
+Ghostscript.
+
+@item @code{point-and-click}
+@tab @code{#f}
+@tab Ajoute les liens @qq{point & click} à la sortie @code{PDF}. Voir
+@ref{Pointer-cliquer}.
+
+@cindex format de sortie, définition
+@cindex preview, ligne de commande
+@item @code{preview}
+@tab @code{#f}
+@tab Génère une prévisualisation en plus de la sortie normale.
+@end multitable
+
+@noindent
+Cette option, disponible dans tous les formats de sortie imprimables --
+@code{pdf}, @code{png}, @code{ps}, @code{eps} et @code{svg} -- génère
+un fichier de la forme @code{monFichier.preview.extension} comprenant le
+titrage et le premier système. S'il existe plusieurs sections
+@code{\book}, @code{\bookpart}, ce fichier contiendra les titrage et
+premier système de chacun des @code{\book}, @code{\bookpart} et
+@code{\score}, dès lors que la variable @code{print-all-headers} du bloc
+@code{\paper} est activée.
+
+Pour l'éviter, utilisez conjointement l'une des options
+@option{-dprint-pages} ou @option{-dno-print-pages} selon vos besoins.
+
+@multitable @columnfractions .33 .16 .51
+@item @code{print-pages}
+@tab @code{#t}
+@tab Génère l'intégralité des pages de la partition. L'option
+@option{-dno-print-pages} est particulièrement utile lorsqu'utilisée
+conjointement avec l'option @option{-dpreview}.
+
+@item @code{profile-property-accesses}
+@tab @code{#f}
+@tab Enregistre des statistiques des appels à la fonction
+@code{get_property()}.
+
+@item @code{protected-scheme-parsing}
+@tab @code{#t}
+@tab Continue en dépit des erreurs que l'analyseur syntaxique
+détecterait dans du code Scheme inclus. Lorsque basculé sur @code{#f},
+stoppe le traitement s'il y a erreur et affiche une trace de la pile.
+
+@item @code{read-file-list}
+@tab @code{#f [fichier]}
+@tab Spécifie un fichier listant les différents fichier sources à
+traiter.
+
+@item @code{relative-includes}
+@tab @code{#f}
+@tab Face à une instruction @code{\include}, recherche les fichiers à
+inclure relativement à l'endroit où se trouve le fichier en cours de
+traitement plutôt que par rapport au fichier maître.
+
+@item @code{resolution}
+@tab @code{101}
+@tab Détermine, en @code{dpi}, la résolution des pixmaps @code{PNG} à
+générer selon la valeur donnée.
+
+@item @code{safe}
+@tab @code{#f}
+@tab Ne pas avoir une confiance aveugle dans le code @file{.ly}.
+@end multitable
+
+@noindent
+Lorsque LilyPond est accessible au travers d'un serveur web, il est
+@strong{impératif} d'utiliser les options @option{--safe} ou
+@option{--jail}. L'option @option{--safe} aura pour effet d'empêcher
+tout code Scheme inclus de mettre en péril votre installation grâce à
+quelque chose du style
+
+@quotation
+@verbatim
+#(system "rm -rf /")
+{
+ c4^$(ly:gulp-file "/etc/passwd")
+}
+@end verbatim
+@end quotation
+
+L'option @code{-dsafe} forcera l'évaluation, au fil de l'eau et par un
+module sécurisé, des expressions Scheme contenues dans le fichier
+source. Ce module sécuritaire, dérivé du module GUILE @file{safe-r5rs},
+ajoute un certain nombre de fonctions -- listées dans
+@file{scm/safe-lily.scm} -- à l'API de LilyPond.
+
+De plus, le mode @emph{safe} ne permet ni l'utilisation de directives
+@code{\include} ni le recours aux obliques inversées (@emph{backslash})
+dans les chaînes @TeX{}. L'import de variables LilyPond dans du code
+Scheme n'est pas possible en mode sécuritaire.
+
+L'option @code{-dsafe} @strong{ne détecte pas} l'utilisation abusive des
+ressources. Il est donc possible que le programme finisse par rester
+sans réponse si on lui envoie une boucle sans fin. C'est la raison pour
+laquelle nous recommandons, lorsque LilyPond tourne sur un serveur
+accessible au public, d'en limiter aussi bien les ressources processeur
+que mémoire.
+
+Notez bien que l'utilisation du mode sécuritaire empêchera aussi la
+compilation d'un certain nombre de fragments LilyPond. L'option
+@code{--jail} est dans ce cas une excellente alternative en terme de
+sécurité, même si elle requiert plus de temps à mettre en place -- voir
+@ref{Options basiques de lilypond}.
+
+@multitable @columnfractions .33 .16 .51
+@item @code{separate-log-files}
+@tab @code{#f}
+@tab Pour les fichiers @code{FICHIER1.ly}, @code{FICHIER2.ly} etc.
+enregistre le déroulement dans les journaux @code{FICHIER1.log},
+@code{FICHIER2.log}@dots{}
+
+@item @code{show-available-fonts}
+@tab @code{#f}
+@tab Liste le nom des fontes disponibles.
+
+@item @code{strict-infinity-checking}
+@tab @code{#f}
+@tab Force le crash en présence des points d'exception de virgule
+flottante @code{Inf} ou @code{NaN} -- infini ou non-nombre.
+
+@item @code{strip-output-dir}
+@tab @code{#t}
+@tab Supprime, lors du nommage des fichiers résultant, la partie
+correspondant au répertoire des fichiers sources.
+
+@item @code{svg-woff}
+@tab @code{#f}
+@tab Utilise, avec le moteur SVG, les fontes @code{woff}.
+
+@item @code{trace-memory-frequency}
+@tab @code{#f}
+@tab Enregistre l'utilisation de la cellule Scheme plusieurs fois par
+seconde, dans les fichiers @code{FICHIER.stacks} et
+@code{FICHIER.graph}.
+
+@item @code{trace-scheme-coverage}
+@tab @code{#f}
+@tab Enregistre la couverture des fichiers Scheme dans @code{FILE.cov}.
+
+@item @code{verbose}
+@tab @code{#f}
+@tab Passe en mode verbeux, ce qui correspond à un niveau de
+journalisation @code{DEBUG} (lecture seule).
+
+@item @code{warning-as-error}
+@tab @code{#f}
+@tab Considère tous les messages d'avertissement et @qq{erreur de
+programmation} comme étant de véritables erreurs.
+@end multitable
@node Variables d'environnement
-@subsection Variables d'environnement
+@unnumberedsubsec Variables d'environnement
@translationof Environment variables
-@untranslated
+@cindex LANG
+@cindex LILYPOND_DATADIR
+
+@command{lilypond} reconnaît les variables d'environnement
+suivantes@tie{}:
+
+@table @code
+@item LILYPOND_DATADIR
+Cette variable spécifie le répertoire où seront recherchés par défaut
+les différentes versions des messages ainsi qu'un certain nombre de
+fichiers nécessaires au traitement. Il devrait contenir les
+sous-répertoires @file{ly/}, @file{ps/}, @file{tex/}, etc.
+
+@item LANG
+Cette variable détermine la langue dans laquelle seront émis les
+messages.
+
+@item LILYPOND_LOGLEVEL
+Cette variable détermine le niveau par défaut de verbosité. En
+l'absence de niveau explicite -- autrement dit la ligne de commande ne
+comporte pas de @option{--loglevel} -- c'est cette valeur qui sera
+utilisée.
+
+@item LILYPOND_GC_YIELD
+Cette variable permet d'ajuster l'empreinte mémoire et le rendement de
+la machine. Il s'agit en fait d'un pourcentage d'allocation de
+mémoire@tie{}: lorsqu'il est élevé, le programme favorisera
+l'utilisation de la mémoire@tie{}; une faible valeur consommera plus de
+temps processeur. Par défaut, cette valeur est fixée à@tie{}@code{70}.
+
+@end table
+
+
+@node Exécution de LilyPond en mode protégé
+@unnumberedsubsec Exécution de LilyPond en mode protégé
+@translationof LilyPond in chroot jail
+
+Paramétrer un serveur afin qu'il puisse faire fonctionner LilyPond en
+mode protégé sur un pseudo-périphérique est une tâche sensible. Les
+différentes étapes à suivre sont répertoriées ci-dessous. Les exemples
+qu'elle comportent proviennent d'une distribution Linux Ubuntu et
+nécessiteront l'utilisation de @code{sudo} autant que de besoin.
+
+@itemize
+
+@item Installation des paquetages nécessaires@tie{}: LilyPond, Ghostscript et
+ImageMagick.
+
+@item Création de l'utilisateur @code{lily} :
+
+@example
+adduser lily
+@end example
+
+@noindent
+Ceci, par la même occasion, créera un groupe spécifique pour
+l'utilisateur @code{lily} ainsi que son répertoire personnel
+@code{/home/lily}.
+
+@item Création, dans le répertoire personnel de l'utilisateur
+@code{lily}, d'un espace agissant en tant que système de fichiers@tie{}:
+
+@example
+dd if=/dev/zero of=/home/lily/loopfile bs=1k count= 200000
+@end example
+
+@noindent
+Cette commande a créé un fichier de 200@tie{}MB utilisable par le
+@qq{système protégé}.
+
+@item Création d'un pseudo-périphérique, génération d'un système de
+fichiers et chargement de celui-ci, puis création d'un répertoire
+accessible en écriture pour l'utilisateur @code{lily}@tie{}:
+
+@example
+mkdir /mnt/lilyloop
+losetup /dev/loop0 /home/lily/loopfile
+mkfs -t ext3 /dev/loop0 200000
+mount -t ext3 /dev/loop0 /mnt/lilyloop
+mkdir /mnt/lilyloop/lilyhome
+chown lily /mnt/lilyloop/lilyhome
+@end example
+
+@item Affectation, au niveau configuration du serveur, de
+@code{/mnt/lilyloop} en tant que JAIL et @code{/lilyhome} en tant que
+DIR.
+
+@item Création d'une arborescence, dans l'espace protégé, et recopie de
+tous les fichiers nécessaires -- voir le script plus loin.
+
+Le recours à l'utilitaire @code{sed} permet de créer les commandes de
+copie de tout ce qui est nécessaire à un exécutable@tie{}:
+
+@example
+for i in "/usr/local/lilypond/usr/bin/lilypond" "/bin/sh" "/usr/bin/; \
+ do ldd $i | sed 's/.*=> \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& \
+ cp -L \/\1\2 \1\2/' | sed 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \
+ \1 \&\& cp -L \/\1\2 \1\2/' | sed '/.*=>.*/d'; done
+@end example
+
+@end itemize
+
+@subheading Exemple de script fonctionnel en 32-bit sur Ubuntu 8.04
+
+@example
+#!/bin/sh
+## les réglages par défaut
+
+username=lily
+home=/home
+loopdevice=/dev/loop0
+jaildir=/mnt/lilyloop
+# le préfixe (sans slash au début !)
+lilyprefix=usr/local
+# le répertoire du système où lilypond est installé
+lilydir=/$lilyprefix/lilypond/
+
+userhome=$home/$username
+loopfile=$userhome/loopfile
+adduser $username
+dd if=/dev/zero of=$loopfile bs=1k count=200000
+mkdir $jaildir
+losetup $loopdevice $loopfile
+mkfs -t ext3 $loopdevice 200000
+mount -t ext3 $loopdevice $jaildir
+mkdir $jaildir/lilyhome
+chown $username $jaildir/lilyhome
+cd $jaildir
+
+mkdir -p bin usr/bin usr/share usr/lib usr/share/fonts $lilyprefix tmp
+chmod a+w tmp
+
+cp -r -L $lilydir $lilyprefix
+cp -L /bin/sh /bin/rm bin
+cp -L /usr/bin/convert /usr/bin/gs usr/bin
+cp -L /usr/share/fonts/truetype usr/share/fonts
+
+# la formule magique de recopie des bibliothèques
+for i in "$lilydir/usr/bin/lilypond" "$lilydir/usr/bin/guile" "/bin/sh" \
+ "/bin/rm" "/usr/bin/gs" "/usr/bin/convert"; do ldd $i | sed 's/.*=> \
+ \/\(.*\/\)\([^(]*\).*/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' | sed \
+ 's/\t\/\(.*\/\)\(.*\) (.*)$/mkdir -p \1 \&\& cp -L \/\1\2 \1\2/' \
+ | sed '/.*=>.*/d'; done | sh -s
+
+# les fichiers partagés pour ghostscript...
+ cp -L -r /usr/share/ghostscript usr/share
+# les fichiers partagés pour ImageMagick
+ cp -L -r /usr/lib/ImageMagick* usr/lib
+
+### Partant du principe que test.ly est dans /mnt/lilyloop/lilyhome,
+### on devrait pouvoir lancer :
+### Attention : /$lilyprefix/bin/lilypond est un script qui
+### définit LD_LIBRARY_PATH - c'est primordial
+ /$lilyprefix/bin/lilypond -jlily,lily,/mnt/lilyloop,/lilyhome test.ly
+@end example
@node Messages d'erreur
@section Messages d'erreur
@translationof Error messages
-@untranslated
+@cindex erreur, messages
+
+Différents messages d'erreur sont susceptibles d'apparaître au cours de
+la compilation d'un fichier@tie{}:
+
+@table @emph
+
+@item Warning -- Avertissement
+@cindex warning
+@cindex avertissement
+Ce type de message est émis lorsque LilyPond détecte quelque chose de
+suspect. Si vous avez demandé quelque chose qui sort de l'ordinaire,
+vous saurez probablement ce à quoi il est fait référence et ignorerez de
+tels messages sans remord. Néanmoins, les messages d'avertissement
+indiquent la plupart du temps une incohérence dans le fichier source.
+
+@item Error -- Erreur
+@cindex error
+LilyPond a détecté une erreur. L'étape en cours, qu'il s'agisse de
+l'analyse, de l'interprétation des données ou bien du formatage, sera
+menée à son terme, puis LilyPond s'arrêtera.
+
+@item Fatal error -- Erreur fatale
+@cindex fatal error
+LilyPond est confronté à une anomalie bloquante. Ceci ne se produit que
+très rarement, et la plupart du temps en raison d'une installation
+défectueuse des fontes.
+
+@item Scheme error -- Erreur Scheme
+@cindex trace, Scheme
+@cindex call trace
+@cindex Scheme error
+Les erreurs qui interviennent lors de l'exécution de code Scheme sont
+gérées par l'interpréteur Scheme. L'utilisation du mode verbeux
+(options @option{-V} ou @option{--verbose}) vous permettra de localiser
+l'appel de fonction délictueux.
+
+@item Programming error -- Erreur de programmation
+@cindex Programming error
+@cindex Erreur de programmation
+LilyPond est confronté à une incohérence interne. Ce type de message
+est destiné à venir en aide aux développeurs et débogueurs. En règle
+générale, vous pouvez tout simplement les ignorer. Parfois, il y en a
+tant qu'ils masquent ce qui pourrait vous intéresser@dots{}
+
+@item Aborted (core dumped) -- Abandon
+@cindex Aborted (core dumped)
+Ce type de message indique que LilyPond a planté en raison d'une grave
+erreur de programmation. La survenance d'un tel message est considérée
+comme de la plus haute importance. Si vous y étiez confronté,
+transmettez un rapport de bogue.
+@end table
+
+@cindex errors, message format
+Lorsque l'avertissement ou l'erreur est directement lié au fichier
+source, le message est libellé sous la forme
+
+@example
+@var{fichier}:@var{ligne}:@var{colonne}: @var{message}
+@var{contenu de la ligne litigieuse}
+@end example
+
+Un saut de ligne est placé dans la ligne de code, indiquant l'endroit
+précis du problème, comme ici@tie{}:
+
+@example
+test.ly:2:19: erreur: n'est pas une durée: 5
+ @{ c'4 e'
+ 5 g' @}
+@end example
+
+Notez que ces coordonnées constituent l'approximation au mieux par
+LilyPond dans le code ayant déclenché l'avertissement ou l'erreur. En
+règle générale, erreurs et avertissements surviennent lorsque LilyPond
+rencontre quelque chose d'inattendu. Lorsque la ligne indiquée ne vous
+semble pas comporter d'élément litigieux, remontez de quelques lignes
+dans votre code.
+Vous trouverez d'autres informations sur les erreurs au chapitre
+@ref{Quelques erreurs des plus courantes}.
-@node Mise à jour des fichiers avec convert-ly
-@section Mise à jour avec @command{convert-ly}
-@translationof Updating files with convert-ly
-@untranslated
+@node Quelques erreurs des plus courantes
+@section Quelques erreurs des plus courantes
+@translationof Common errors
+Les conditions amenant aux erreurs qui suivent sont fréquentes, bien
+qu'elles ne soient pas évidentes ni facilement localisables. Nous
+espérons que ces explications vous aideront à les résoudre plus
+facilement.
-@subsection Options en ligne de commande
@menu
-* Limitations de convert-ly::
+* La musique déborde de la page::
+* Apparition d'une portée supplémentaire::
+* Erreur renvoyant à ../ly/init.ly::
+* Message d'erreur Unbound variable %::
+* Message d'erreur FT_Get_Glyph_Name::
+* staff-affinities devraient aller en ordre décroissant::
@end menu
-@node Limitations de convert-ly
-@subsection Limitations de @command{convert-ly}
-@translationof Problems with convert-ly
-@untranslated
+@node La musique déborde de la page
+@unnumberedsubsec La musique déborde de la page
+@translationof Music runs off the page
+
+Lorsque la musique s'épanche au delà de la marge droite ou bien semble
+anormalement comprimée, la raison en est le plus souvent une note à la
+durée erronée@tie{}; cela finit par provoquer le débordement de la
+dernière note d'une mesure. Rien ne s'oppose à ce que la dernière note
+d'une mesure ne s'arrête avant la barre de mesure@tie{}; on considère
+simplement qu'elle se prolonge sur la mesure suivante. Des débordements
+à répétition finissent par générer une musique comprimée ou qui sort de
+la page, pour la simple et bonne raison que les sauts de ligne
+automatiques ne peuvent intervenir qu'à la fin d'une mesure complète,
+autrement dit lorsque toutes les notes sont terminées avant la fin de la
+mesure.
+
+@warning{Une durée erronée peut empêcher les sauts de ligne, ce qui
+conduit à une musique compressée, voire à un débordement de la page.}
+
+Une erreur de durée sera bien plus facilement localisable si vous
+positionnez régulièrement des contrôles de barre de mesure -- voir
+@ruser{Vérification des limites et numéros de mesure}.
+
+Si vous tenez absolument à enchaîner de tels débordements, vous devrez
+insérer des barres de mesure invisibles là où vous souhaitez positionner
+un saut de ligne. Consultez le chapitre @ruser{Barres de mesure} pour
+plus de détails.
+
+
+@node Apparition d'une portée supplémentaire
+@unnumberedsubsec Apparition d'une portée supplémentaire
+@translationof An extra staff appears
+
+Lorsque les contextes ne sont pas créés explicitement par la commande
+@code{\new}, ils le seront si la commande à exécuter n'est pas censée
+s'appliquer au contexte en cours. Pour des partitions simples, le fait
+que les contextes soient automatiquement créés rend bien des services,
+et c'est d'ailleurs le cas pour la majorité des exemples contenus dans
+les manuels de LilyPond. Cependant, la création implicite d'un contexte
+peut aboutir à l'apparition d'une portée @qq{parasite}. On s'attend par
+exemple, en lisant le code qui suit, à ce que toutes les têtes de note
+soient en rouge, alors que le résultat nous présente deux portées et que
+les notes, placées sur la portée inférieure, restent en noir.
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.NoteHead #'color = #red
+\new Staff { a }
+@end lilypond
+
+Étant donné qu'aucun contexte @code{Staff} n'existe lorsque la
+dérogation est introduite, LilyPond le crée implicitement pour lui
+appliquer la directive considérée. Survient alors la commande
+@w{@code{\new Staff}} qui, à son tour, crée une nouvelle portée pour
+contenir les notes qui suivent. Voici la syntaxe correcte pour obtenir
+ces notes en rouge@tie{}:
+
+@lilypond[quote,verbatim,relative=2]
+\new Staff {
+ \override Staff.NoteHead #'color = #red
+ a
+}
+@end lilypond
+
+Autre exemple : la présence d'une commande @code{\relative} à
+l'intérieur d'une section @code{\repeat} générera obligatoirement une
+portée intempestive. Cela tient au fait que la commande @code{\repeat}
+va créer deux blocs @code{\relative} qui, chacun à leur tour, créeront
+implicitement un bloc @code{Staff} assorti d'un bloc @code{Voice}.
+
+@lilypond[quote,verbatim]
+\repeat unfold 2 {
+ \relative c' { c4 d e f }
+}
+@end lilypond
+
+La manière adéquate de procéder consiste à inverser les commandes
+@code{\repeat} et @code{\relative}, comme ceci@tie{}:
+
+@lilypond[quote,verbatim]
+\new Voice {
+ \repeat unfold 2 {
+ \relative c' { c4 d e f }
+ }
+}
+@end lilypond
+
+
+@node Erreur renvoyant à ../ly/init.ly
+@unnumberedsubsec Erreur renvoyant à @code{../ly/init.ly}
+@translationof Apparent error in ../ly/init.ly
+
+Certains messages d'erreur relatifs à une erreur de syntaxe dans le
+fichier @file{../ly/init.ly} peuvent survenir lorsque le fichier est mal
+formaté. Cela se produit notamment lors d'un défaut de parité de
+bornages ou de guillemets.
+
+L'erreur la plus courante est la simple omission d'une accolade
+fermante (@code{@}}) à la fin du bloc @code{Score}. La solution est
+évidente en pareil cas@tie{}: il suffit de vérifier que le bloc
+@code{Score} est bien clôturé. La structure des fichiers LilyPond est
+abordée plus en détails au chapitre
+@rlearning{Organisation des fichiers LilyPond}. C'est la raison pour
+laquelle nous vous invitons à utiliser un éditeur de texte qui prenne en
+charge le contrôle de parité des parenthèses, crochets et accolades afin
+de vous éviter de telles erreurs.
+
+Autre erreur courante, l'absence d'espace entre la dernière syllabe et
+l'accolade (@code{@}}) clôturant un bloc de paroles. Lorsqu'il n'y a
+pas séparation, l'accolade est considérée comme faisant partie
+intégrante de la syllabe. C'est la raison pour laquelle nous vous
+invitons à insérer une espace avant et après @strong{chaque} accolade.
+D'autres informations à ce sujets sont mentionnées au chapitre
+@ruser{Saisie des paroles}.
+
+Lorsqu'il s'agit d'un guillemet fermant (@code{"}) omis, le message
+d'erreur devrait vous indiquer un numéro de ligne avoisinant. L'erreur
+se situe la plupart du temps une ou deux lignes au-dessus de celle
+indiquée.
+@c Match quote character "
+
+@node Message d'erreur Unbound variable %
+@unnumberedsubsec Message d'erreur Unbound variable %
+@translationof Error message Unbound variable %
+
+Ce message d'erreur, qu'il apparaisse sur le terminal ou en fin de
+fichier journal, est associé à un message du type @qq{GUILE a signalé
+une erreur@dots{}}. Il survient à chaque fois qu'un commentaire
+@emph{LilyPond} est indûment placé dans une routine @emph{Scheme}.
+
+Un commentaire LilyPond est introduit par le signe pourcent (@code{%})
+et ne doit en aucun cas se trouver dans une routine Scheme. En Scheme,
+les commentaires s'introduisent par un point-virgule (@code{;}).
+
+
+@node Message d'erreur FT_Get_Glyph_Name
+@unnumberedsubsec Message d'erreur FT_Get_Glyph_Name
+@translationof Error message FT_Get_Glyph_Name
+Ce message d'erreur, qu'il apparaisse sur le terminal ou en fin de
+fichier journal, survient lorsqu'un fichier source contient des
+caractères non ASCII et qu'il n'a pas été enregistré avec un encodage
+UTF-8. Pour plus de détails, reportez-vous au chapitre
+@ruser{Caractères spéciaux}.
-@node Rapport de bogue
-@section Rapport de bogue
-@translationof Reporting bugs
-@untranslated
+@node staff-affinities devraient aller en ordre décroissant
+@unnumberedsubsec staff-affinities devraient aller en ordre décroissant
+@translationof Warning staff affinities should only decrease
+Cet avertissement est émis lorsque la partition ne comporte pas de
+portée, comme par exemple une feuille de chant avec un contexte
+@code{ChordName} et un contexte @code{Lyrics}. Ce message disparaîtra
+dès lors que autoriserez l'un de ces contextes à se comporter comme une
+portée, à l'aide de l'instruction
+@example
+\override VerticalAxisGroup #'staff-affinity = ##f
+@end example
+@noindent
+que vous insérerez dès sa création. Pour plus d'information,
+reportez-vous à la rubrique
+@ruser{Espacement des lignes rattachées à des portées}.
projects / lilypond.git / blobdiff