@section Travail sur des fichiers texte
@translationof Working with input files
-@untranslated
-
-
@menu
* Insertion de fichiers LilyPond::
* Différentes éditions à partir d'une même source::
@subsection Insertion de fichiers LilyPond
@translationof Including LilyPond files
-@untranslated
+@funindex \include
+@cindex inclusion de fichiers
+
+Lorsqu'un projet prend de l'importance en volume, il est judicieux de le
+scinder en plusieurs fichiers, auxquels vous fereez référence avec un
+simple
+
+@example
+\include "autrefichier.ly"
+@end example
+
+Une ligne @code{\include "autrefichier.ly"} dans un fichier revient à
+recopier intégralement le contenu de @file{autrefichier.ly} à l'endroit
+même ou est placée l'instruction @code{\include}. Vous pouvez par
+exemple écrire un fichier individuel par instrument, puis les regrouper
+pour former le fichier @qq{conducteur}. Les différentes variables
+définies dans les fichiers séparés seront normalement reprises et
+utilisables dans le fichier formant le conducteur. Les sections
+balisées dans les fichiers individuels peuvent être réutilisées en
+différents endroit de la partition , comme expliqué à la rubrique
+@ref{Différentes éditions à partir d'une même source}.
+
+Lorsque le fichier auquel il est fait référence se trouve dans le même
+répertoire, donner seulement son nom en argument à la commande
+@code{\include} suffit. S'il se trouve ailleurs, vous devrez indiquer
+le chemin d'accès, absolu ou relatif, en respectant toutefois la syntaxe
+UNIX -- autrement dit, le séparateur de répertoire est une oblique
+normale @code{/} et non l'oblique inverse @code{\} de DOS/Windows. Par
+exemple, si le fichier @file{truc.ly} se trouve dans le répertoire
+supérieur au répertoire de travail, la ligne devra être
+
+@example
+\include "../stuff.ly"
+@end example
+
+@noindent
+ou bien, si les fichiers correspondant aux parties d'orchestre se
+trouvent dans le sous-répertoire @file{parties} relativement au
+répertoire courant, vous devrez mentionner
+
+@example
+\include "parties/VI.ly"
+\include "parties/VII.ly"
+... etc.
+@end example
+
+Les fichiers à inclure peuvent eux-même contenir des instructions
+@code{\include}. Ces instructions @code{\include} de second niveau ne
+pourront, par défaut, être interprétées qu'une fois intégrées dans le
+fichier principal@tie{}; leur argument doit donc comporter le chemin
+relativement au fichier principal et non par rapport au fichier dan
+lesquel cette inclusion est mentionnée. Vous pouvez toutefois influer
+sur ce comportement à l'aide de l'option @code{-drelative-includes} en
+ligne de commande ou en ajoutant une clause
+@code{@w{#(ly:set-option 'relative-includes #t)}} en tête du fichier
+principal. Une fois @code{relative-include} activé, le chemin à suivre
+pour chacune des commandes @code{\include} sera pris relativement au
+fichier qui la contient.
+
+Vous pouvez inclure des fichiers dont vous spécifierez le chemin d'accès
+sur la ligne de commande au moment de lancer la compilation. L'appel à
+ces fichiers ne mentionnerra alors que leur nom. Par exemple, si vous
+voulez compiler avec cette méthode le fichier @file{principal.ly} qui
+inclut des fichiers situés dans le sous-répertoire @file{parties},
+placez vous dans le répertoire contenant @file{principal.ly}, puis tapez
+
+@example
+lilypond --include=parties principal.ly
+@end example
+
+tout en ayant bien dans @file{principal.ly}
+
+@example
+\include "VI.ly"
+\include "VII.ly"
+... etc
+@end example
+
+Lorsqu'un fichier est voué à être inclus dans nombre de partitions, vous
+pouvez le placer dans le répertoire de LilyPond @file{../ly}.
+Attention@tie{}: ce répertoire varie selon votre installation, comme
+indiqué au chapitre @rlearning{Autres sources de documentation}. Ce
+fichier sera inclus dès lors que vous fournirez uniquement son nom en
+argument à la fonction @code{\include}. C'est par exemple le cas du
+fichier de définition particulier @file{gregorian.ly}.
+
+Au moment où vous lancez LilyPond, un certain nombre de fichiers se
+retrouvent inclus par défaut@tie{}; il suffit d'activer le mode verbeux
+en faisant @code{lilypond --verbose} pour s'en rendre compte. Vous
+verrez ainsi défiler, en plus de nombreuses informations, le nom d'un
+certain nombre de fichier et de chemins d'accès. Les fichiers les plus
+important sont mentionnés au chapitre
+@rlearning{Autres sources de documentation}. Si vous venez à les
+modifier, rappelez-vous qu'ils seront écrasés à l'installation d'une
+nouvelle version de LilyPond.
+
+Vous trouverez quelques exemples simples d'utilisation de la commande
+@code{\include} au chapitre @rlearning{Conducteurs et parties}.
+
+
+@seealso
+Manuel d'initiation :
+@rlearning{Autres sources de documentation},
+@rlearning{Conducteurs et parties}.
+
+
+@knownissues
+
+Lorsque vous incluez un fichier qui porte le même nom que l'un des
+fichiers d'initialisation de LilyPond, le fichier de la distribution de
+LilyPond aura préséance.
@node Différentes éditions à partir d'une même source
@subsection Différentes éditions à partir d'une même source
@translationof Different editions from one source
-@untranslated
-
+Différents mécanismes permettent de générer plusieurs versions d'une
+partition à partir d'une même source. Les variables -- ou
+idendificateurs -- sont sûrement le moyen le plus simple de combiner de
+différente manière des passages relativement longs, alors que les
+balises permettront de sélectionner de courts fragments selon leur
+utilisation. Quelle que soit la méthode utilisée, séparer la notation
+de la structure de la partition vous donnera plus de liberté dans
+l'agencement de l'ouvrage final, puisque vous ne reviendrez pas sur la
+musique qui le compose.
@menu
* Utilisation de variables::
@unnumberedsubsubsec Utilisation de variables
@translationof Using variables
-@untranslated
+@cindex variables, utilisation de
+
+Un fragment musical identifié par une variable est réutilisable à divers
+endroits de la partition, comme nous l'avons vu à la rubrique
+@rlearning{Organisation du code source avec des variables}. Par
+exemple, une partition pour chœur @notation{a cappella} comporte souvent
+une réduction pour piano reprenant toutes les voix@tie{}; il s'agit de
+la même musique, et vous ne devrez donc la saisir qu'une seule fois.
+D'autre part, la musique issue de deux variables peut se combiner sur
+une seule portée, comme nous l'avons vu à la rubrique
+@ref{Regroupement automatique de parties}. Prenons l'exemple
+suivant@tie{}:
+
+@lilypond[verbatim,quote]
+sopranoMusic = \relative c'' { a4 b c b8( a) }
+altoMusic = \relative g' { e4 e e f }
+tenorMusic = \relative c' { c4 b e d8( c) }
+bassMusic = \relative c' { a4 gis a d, }
+allLyrics = \lyricmode {King of glo -- ry }
+<<
+ \new Staff = "Soprano" \sopranoMusic
+ \new Lyrics \allLyrics
+ \new Staff = "Alto" \altoMusic
+ \new Lyrics \allLyrics
+ \new Staff = "Tenor" {
+ \clef "treble_8"
+ \tenorMusic
+ }
+ \new Lyrics \allLyrics
+ \new Staff = "Bass" {
+ \clef "bass"
+ \bassMusic
+ }
+ \new Lyrics \allLyrics
+ \new PianoStaff <<
+ \new Staff = "RH" {
+ \set Staff.printPartCombineTexts = ##f
+ \partcombine
+ \sopranoMusic
+ \altoMusic
+ }
+ \new Staff = "LH" {
+ \set Staff.printPartCombineTexts = ##f
+ \clef "bass"
+ \partcombine
+ \tenorMusic
+ \bassMusic
+ }
+ >>
+>>
+@end lilypond
+
+Générer une partition chorale ou la réduction pour piano ne requiert que
+de modifier la structure des éléments, sans aucunement toucher à la
+musique.
+
+Dans le cas d'une partition relativement longue, vous pouvez isoler la
+définition des différentes variables dans des fichiers séparés que vous
+rappellerez ensuite, comme indiqué à la rubrique
+@ref{Insertion de fichiers LilyPond}.
@node Utilisation de balises
@unnumberedsubsubsec Utilisation de balises
@translationof Using tags
+
@funindex \tag
+@funindex \keepWithTag
+@funindex \removeWithTag
@cindex tag
+@cindex balise
+
+La commande @code{\tag #'@var{partieA}} affecte à une expression
+musicale le nom @var{partieA}. Les expressions ainsi balisées pourront
+être filtrées par la suite, à l'aide de
+@code{\keepWithTag@tie{}#'@var{nom}} ou
+@code{\removeWithTag@tie{}#'@var{nom}}. Ces filtres fonctionnent de la
+manière suivante@tie{}:
+
+@multitable @columnfractions .5 .5
+@headitem Filtre
+ @tab Résultat
-La commande @code{\tag} affecte un nom à des expressions musicales.
-Les expressions ainsi balisées pourront être filtrées par la suite.
-Ce mécanisme permet d'obtenir différentes versions à partir d'une même
-source musicale.
+@item
+Musique balisée précédée de @code{\keepWithTag #'@var{nom}}
+ @tab Musique non balisée et musique balisée par @var{nom} seront
+ incluses@tie{}; la musique balisée autrement est exclue.
+
+@item
+Musique balisée précédée de @code{\removeWithTag #'@var{nom}}
+ @tab Musique non balisée et fragments appelés autrement que @var{nom}
+ seront inclus@tie{}; la musique balisée par @var{nom} est exclue.
+
+@item
+Musiqeu balisée non précédée de @code{\keepWithTag} ou
+@code{\removeWithTag}
+ @tab Musique balisée et non balisée seront incluses.
+
+@end multitable
+
+Les arguments des commandes @code{\tag}, @code{\keepWithTag} et
+@code{\removeWithTag} doivent être un symbole (tel que
+@code{#'conducteur} ou @code{#'partie}), suivi d'une expression
+musicale.
Dans l'exemple qui suit, nous obtenons deux versions du même extrait,
l'une pour le conducteur, l'autre pour l'instrumentiste, et qui
-comportera les ornements.
+comportera les ornements développés.
-@example
-c1
-<<
- \tag #'partie <<
- R1 \\
- @{
- \set fontSize = #-1
- c4_"cue" f2 g4 @}
- >>
- \tag #'conducteur R1
->>
-c1
-@end example
+@lilypond[verbatim,quote]
+music = \relative g' {
+ g8. c32 d
+ \tag #'trills { d8.\trill }
+ \tag #'expand { \repeat unfold 3 { e32 d } }
+ c32 d
+ }
+
+\score {
+ \keepWithTag #'trills \music
+}
+\score {
+ \keepWithTag #'expand \music
+}
+@end lilypond
@noindent
-Ce principe peut s'appliquer aux articulations, textes, etc. Il
-suffit de positionner
+Il est parfois plus aisé d'exclure des fragments@tie{}:
+
+@lilypond[verbatim,quote]
+music = \relative g' {
+ g8. c32 d
+ \tag #'trills { d8.\trill }
+ \tag #'expand {\repeat unfold 3 { e32 d } }
+ c32 d
+ }
+
+\score {
+ \removeWithTag #'expand
+ \music
+}
+\score {
+ \removeWithTag #'trills
+ \music
+}
+@end lilypond
+
+Ce principe de filtrage peut s'appliquer aux articulations, textes, etc.
+Il suffit de positionner
@example
--\tag #@var{votre-balise}
+-\tag #@var{ma-balise}
@end example
@noindent
-avant l'articulation, comme ici :
+avant l'articulation ou le texte, comme ici :
@example
-c1-\tag #'part ^4
+c1-\tag #'doigt ^4
+c1-\tag #'gaffe ^"Attention !"
@end example
@noindent
-Ceci définira une note avec une indication de doigté conditionnelle.
+Ceci définira une note avec une indication conditionnelle de doigté ou
+un texte.
-@cindex keepWithTag
-@cindex removeWithTag
-C'est grâce aux commandes @code{\keepWithTag} et @code{\removeWithTag}
-que vous filtrerez les expressions balisées. Par exemple :
+Vous pouvez baliser différemment la même expression musicale en
+saisissant plusieurs @code{\tag}@tie{}:
-@example
+@lilypond[quote,verbatim]
+music = \relative c'' {
+ \tag #'a \tag #'both { a4 a a a }
+ \tag #'b \tag #'both { b4 b b b }
+}
<<
- @var{de la musique}
- \keepWithTag #'score @var{de la musique}
- \keepWithTag #'part @var{de la musique}
+\keepWithTag #'a \music
+\keepWithTag #'b \music
+\keepWithTag #'both \music
>>
-@end example
+@end lilypond
-@noindent
-donnerait :
+L'application concomitante de plusieurs filtres @code{\removeWithTag} à
+la même expression musicale permet d'exclure plusieurs balisages@tie{}:
-@lilypondfile[ragged-right,quote]{tag-filter.ly}
+@lilypond[verbatim,quote]
+music = \relative c'' {
+\tag #'A { a4 a a a }
+\tag #'B { b4 b b b }
+\tag #'C { c4 c c c }
+\tag #'D { d4 d d d }
+}
+{
+\removeWithTag #'B
+\removeWithTag #'C
+\music
+}
+@end lilypond
-Les arguments de la commande @code{\tag} doivent être un symbole (tel
-que @code{#'score} ou @code{#'part}), suivi d'une expression musicale.
-Vous pouvez utiliser de multiples balises dans un morceau en
-saisissant plusieurs @code{\tag}.
+L'application de plus d'un filtre @code{\keepWithTag} à la même
+expression musicale aboutit à l'exclusion de @b{tous} les balisages.
+En effet, si le premier filtre exclut tous les autres balisages,
+l'application du second exclura les effets du premier.
-@example
-\tag #'original-part \tag #'transposed-part @dots{}
-@end example
-@ignore
-FIXME
@seealso
-Exemples : @lsr{parts,tag@/-filter@/.ly}
-@end ignore
+Manuel d'initiation :
+@rlearning{Organisation du code source avec des variables}.
+
+Manuel de notation :
+@ref{Regroupement automatique de parties},
+@ref{Insertion de fichiers LilyPond}.
+
+@ignore
+@c This warning is more general than this placement implies.
+@c Rests are not merged whether or not they come from tagged sections.
+@c Should be deleted? -td
@knownissues
Lorsqu'elles comportent des silences, ceux-ci ne seront pas fusionnés
si vous imprimez une partition avec les deux sections balisées.
+@end ignore
+
@node Codage du texte
@subsection Codage du texte
@translationof Text encoding
-@untranslated
+@cindex Unicode
+@cindex UTF-8
+@cindex non-ASCII characters
+
+LilyPond utilise le jeu de caractères défini par le consortium Unicode
+et la norme ISO/CEI@tie{}10646. Chaque caractère est identifié par un
+nom unique et associé à un point de code, ce qui permet dans l'absolu de
+couvrir tous les langages. Unicode permet de coder tous les caractères
+utilisés par toutes les langues écrites du monde. LilyPond utilise le
+codage UTF-8 (UTF pour @emph{Unicode Transformation Format}) qui permet
+de représenter les caractères latins sur un octet et les autres sur une
+longueur allant jusqu'à quatre octets.
+
+L'apparence réelle des caractères est déterminée par les glyphes ou
+graphèmes tels que définis dans les différentes polices disponibles.
+Une police, ou une fonte, définit la mise en correspondance d'un
+sous-ensemble de points de code unicode en glyphes. LilyPond recourt à
+la bibliothèque Pango pour assurer le rendu des textes multilingues.
+
+LilyPond n'effectue aucune conversion d'encodage que ce soit. Ceci
+implique donc que tout texte, qu'il s'agisse d'un titre, de paroles ou
+même d'instruction musicale, comportant des caractères non ASCII soit
+codé en UTF-8. Le plus sûr moyen de saisir du texte de la sorte
+consiste à utiliser un éditeur supportant l'unicode et à enregistrer vos
+fichier en UTF-8. C'est le cas pour la plupart des éditeurs actuels,
+que ce soit vim, Emacs, jEdit et GEdit. Tous les systèmes Windows
+postérieurs à NT utilisent Unicode en natif@tie{}; même Notepad est
+capable d'éditer et sauvegarder un fichie en UTF-8 -- sans parler de
+l'excellente alternative qu'est BabelPad.
+
+La compilation d'un fichier LilyPond comportant des caractères non ASCII
+qui n'aurait pas été enregistré dans l'encodage UTF-8 vous renverra
+l'erreur
+
+@example
+FT_Get_Glyph_Name () erreur : invalid argument
+@end example
+
+Voici un exemple utilisant du texte en cyrilique, en hébreux et en
+portugais.
+
+@lilypond[quote]
+%c No verbatim here as the code does not display correctly in PDF
+% Cyrillic
+bulgarian = \lyricmode {
+ Жълтата дюля беше щастлива, че пухът, който цъфна, замръзна като гьон.
+}
+
+% Hebrew
+hebrew = \lyricmode {
+ זה כיף סתם לשמוע איך תנצח קרפד עץ טוב בגן.
+}
+
+% Portuguese
+portuguese = \lyricmode {
+ à vo -- cê uma can -- ção legal
+}
+
+\relative c' {
+ c2 d e f g f e
+}
+\addlyrics { \bulgarian }
+\addlyrics { \hebrew }
+\addlyrics { \portuguese }
+@end lilypond
+
+Lorsque vous avez besoin d'un caractère dont vous connaissez le point de
+code mais que votre éditeur ne permet pas de saisir directement, vous
+pouvez utitliser les instructions @code{\char@tie{}##xhhhh} ou
+@code{\char@tie{}#dddd} au sein d'un bloc @code{\markup} -- @code{hhhh}
+et @code{dddd} correspondant respectivement à la valeur hexadécimale ou
+décimale. Même s'il est inutile de saisir les zéros superflus, il est
+de bon ton de stipuler les quatre caractères formant la représentation
+hexadécimale. Évitez cependant l'encodage UTF-8 d'un point de code
+après un @code{\char}@tie{}; les encodages UTF-8 comprennent un bit
+supplémentaire indiquant le nombre d'octets. Une table de
+correspondance entre les codes Unicode et le nom des caractères ainsi
+que leur code hexadécimal est disponible sur le site du consortium
+Unicode, @uref{http://www.unicode.org/}.
+
+Par exemple, @code{\char ##x03BE} et @code{\char #958} correspondent
+tous deux au caractère unicode U+03BE, dénommé @qq{Greek Small Letter
+Xi}.
+
+Quel que soit le point de code spécifié de cette manière, il ne vous
+sera alors pas nécessaire d'enregistrer votre fichier en UTF-8. Vous
+devrez toutefois disposer d'une fonte contenant ce caractère qui soit
+accessible à LilyPond.
+
+L'exemple suivant illustre la manière d'insérer un caractère sous sa
+forme hexadécimale, à la fois dans un repère, dans une articulation,
+dans des paroles et dans du texte indépendant.
+
+@lilypond[quote,verbatim]
+\score {
+ \relative c'' {
+ c1 \mark \markup { \char ##x03EE }
+ c1_\markup { \tiny { \char ##x03B1 " to " \char ##x03C9 } }
+ }
+ \addlyrics { O \markup { \concat { Ph \char ##x0153 be! } } }
+}
+\markup { "Copyright 2008--2010" \char ##x00A9 }
+@end lilypond
+
+@cindex copyright
+
+Le signe @emph{copyright} dans le champ de titrage consacré s'inscrit de
+la manière suivante@tie{}:
+
+@example
+\header @{
+ copyright = \markup @{ \char ##x00A9 "2008" @}
+@}
+@end example
@node Affichage de notation au format LilyPond
@subsection Affichage de notation au format LilyPond
@translationof Displaying LilyPond notation
-@untranslated
+@funindex \displayLilyMusic
+
+La fonction musicale @code{\displayLilyMusic}, disponible uniquement
+pour un traitement en ligne de commande, permet d'afficher en
+notation LilyPond une expression musicale. Par exemple,
+
+@example
+@{
+ \displayLilyMusic \transpose c a, @{ c4 e g a bes @}
+@}
+@end example
+
+affichera
+
+@example
+@{ a,4 cis e fis g @}
+@end example
+
+LilyPond affichera le résultat sous forme de message en console, au
+milieu de toutes les informations de compilation. Afin d'isoler ces
+messages et enregistrer le résultat de la fonction
+@code{\display@{STUFF@}}, pensez à rediriger la sortie vers un fichier.
+
+@example
+lilypond fichier.ly >display.txt
+@end example
@node Contrôle des sorties
projects / lilypond.git / commitdiff