Merge branch 'lilypond/translation' into staging

[lilypond.git] / Documentation / fr / usage / running.itely

@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-

@ignore
    Translation of GIT committish: 0fcca9bfd579bbda8ef0842baa5cd57b8ba718e2

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.15.18"

@c Translators: Jean-Charles Malahieude
@c Translation checkers:

@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::
* Quelques erreurs des plus courantes::
@end menu

@node Utilisation habituelle
@section Utilisation habituelle
@translationof Normal usage

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

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 pour lilypond::
* Variables d'environnement::
* Exécution de LilyPond en mode protégé::
@end menu

@node Lancement de lilypond
@unnumberedsubsec Lancement de @command{lilypond}
@translationof Invoking lilypond

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 en ligne de commande pour lilypond
@unnumberedsubsec Options en ligne de commande pour @command{lilypond}
@translationof 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

Voici les différentes options disponibles à la ligne de commande@tie{}:

@table @code

@item -d,--define-default=@var{var}=@var{val}
Affecte la valeur Scheme @var{val} à l'option interne @var{var} du
programme.  En l'absence de @var{val}, le programme utilisera @var{#t}.
Préfixer @var{var} 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

Voici les options disponibles@tie{}:

@cindex help, ligne de commande

@table @code

@item help
Lancer @code{lilypond -dhelp} affichera la liste de toutes les options
@code{-d} disponibles.


@cindex paper-size, ligne de commande
@item paper-size
Détermine la taille par défaut du papier, par exemple
@example
-dpaper-size=\"letter\"
@end example

@noindent
Veillez à ne pas oublier d'encadrer la valeur par des guillemets
échappés ( @code{\"} ).
@c Match " in previous line to help context-sensitive editors


@cindex safe, ligne de commande
@item safe
Ne pas avoir une confiance aveugle dans le code @file{.ly}.

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.


@cindex format de sortie, définition
@item backend
Détermine le format de sortie à utiliser par le moteur de traitement.
Les types de @code{format} reconnus sont

@table @code
@item ps

@cindex PostScript output
pour du PostScript.

Les fichiers PostScript incluent les polices TTF, Type1 et OTF, et
aucune substitution ne sera opérée pour ces fontes.  Si vous utilisez
des caractères orientaux, le fichier aura vite fait d'atteindre une
taille conséquente.


@item eps
@cindex Postscript encapsulé
@cindex EPS (Encapsulated PostScript)
pour 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 svg
@cindex SVG (Scalable Vector Graphics)
pour du SVG (@emph{Scalable Vector Graphics}).

Cette option permet de créer un fichier 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 SVG alors générés devraient être
lisibles par votre éditeur SVG habituel.

@item scm
@cindex Scheme dump
pour une recopie brute des commandes Scheme internes de formatage.

@item null
permet de ne pas générer de partition imprimable.  Cette option est
équivalente à @code{-dno-print-pages}.

@end table

Exemple : @code{lilypond -dbackend=svg @var{monfichier}.ly}


@item preview
@cindex preview, ligne de commande
Génère un fichier comprenant le titrage et le premier système.  S'il
existe plusieurs sections @code{\bookpart}, ce fichier contiendra les
titrage et premier système de chacun des @code{\bookpart}.  Cette
option fonctionne pour les moteurs de traitement @code{ps}, @code{eps}
et @code{svg}.

Sera automatiquement généré un fichier additionnel, de la forme
@file{monFichier.preview.extension}.  Pour l'éviter, utilisez
conjointement l'une des options @option{-dprint-pages} ou
@option{-dno-print-pages} selon vos besoins.

@item gui
Travaille silencieusement, et redirige tout le verbiage dans un fichier
journal.

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.

@item print-pages
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}.

@end table


@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 quillements
doubles @code{"} en lieu et place des guillemets simples @code{'}.}
@c Match " in previous line to help 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.

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 aloué à LilyPond -- grâce à @command{ulimit@tie{}-t} par
exemple -- ainsi que, si votre système le permet, la taille de la
mémoire.
@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 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é (p.ex. @file{.pdf} pour du pdf) dans tous
les cas.


@cindex PostScript, output
@cindex PS (PostScript), output
@item --ps
Génère du PostScript.


@item --png
@cindex Portable Network Graphics (PNG), output
@cindex PNG (Portable Network Graphics), output
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


@item --pdf
@cindex Portable Document Format (PDF), output
@cindex PDF (Portable Document Format), output
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 appliquables à GNU LilyPond -- il
est livré @strong{SANS GARANTIE}@tie{}!
@end table


@node Variables d'environnement
@unnumberedsubsec Variables d'environnement
@translationof Environment variables

@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 biblothè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

@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 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.

@menu
* 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 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 à enchainer 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 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}.