@c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
@c This file is part of lilypond.tely
@ignore
- Translation of GIT committish: 64f0d86a7c0987b311bfdfdfeddfa063e1f2d6e7
+ Translation of GIT committish: d0b8b30fb1e461c215c7867ae0aafed730699403
- When revising a translation, copy the HEAD committish of the
- version that you are working on. See TRANSLATION for details.
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
@end ignore
@node Working on LilyPond projects
@chapter Working on LilyPond projects
-UNTRANSLATED NODE: IGNORE ME
+Cette section explique comment résoudre ou éviter certains problèmes
+courants. Si vous avez de l'expérience en programmation, beaucoup de
+ces astuces peuvent vous paraître évidentes, mais vous ne perdrez tout
+de même pas temps à lire ce chapitre.
-@menu
+@menu
* Suggestions for writing LilyPond files::
* Saving typing with identifiers and functions::
* Style sheets::
* Updating old files::
* Troubleshooting (taking it all apart)::
-@end menu
+* Minimal examples::
+@end menu
+
@node Suggestions for writing LilyPond files
@section Suggestions for writing LilyPond files
-UNTRANSLATED NODE: IGNORE ME
+Maintenant vous êtes prêts à travailler sur de plus gros fichiers
+LilyPond --- des pièces entières, et plus seulement les petits
+exemples du tutoriel. Mais comment devriez-vous vous y prendre ?
+
+Tant que LilyPond parvient à comprendre vos fichiers et produit le
+résultat que vous souhaitez, peu importe la manière dont le code est
+organisé. Néanmoins, quelques critères doivent être pris en compte
+lorsque l'on écrit un fichier LilyPond.
+
+@itemize @bullet
+@item Si vous faites une erreur, la structure même du fichier LilyPond
+peut permettre de la trouver plus ou moins facilement.
-@menu
+@item Et si vous souhaitez partager vos fichiers avec quelqu'un
+d'autre, ou si vous souhaitez modifier vos propres fichiers dans
+quelques années ? Si certains fichiers LilyPond sont compréhensibles
+au premier coup d'oeil, d'autres vous feront vous arracher les cheveux
+pendant une heure.
+
+@item Et si vous souhaitez mettre à jour votre fichier pour
+l'utiliser avec une version plus récente de LilyPond ? La syntaxe du
+langage d'entrée change parfois lorsque LilyPond s'améliore. La
+plupart des changements peuvent être appliqués automatiquement avec
+@code{convert-ly}, mais quelques-uns peuvent demander une intervention
+manuelle. Vos fichiers LilyPond peuvent être structurés de manière à
+faciliter leur mise à jour.
+@end itemize
+
+@menu
* General suggestions::
* Typesetting existing music::
* Large projects::
-@end menu
+@end menu
+
@node General suggestions
@subsection General suggestions
-UNTRANSLATED NODE: IGNORE ME
+Voici quelques conseils qui peuvent vous éviter certains problèmes ou
+en résoudre d'autres.
+
+@itemize @bullet
+@item @strong{Ajoutez le numéro de version dans chaque fichier}.
+Notez que chaque fichier modèle contient une ligne @code{\version
+"2.9.13"}. Nous vous conseillons fortement d'inclure cette ligne,
+même pour de petits fichiers. Par expérience, il est très difficile
+de se rappeler quelle version de LilyPond on utilisait quelques
+années auparavant. L'utilitaire @code{convert-ly} demande que vous
+spécifiiez quelle version de LilyPond vous utilisiez.
+
+@item @strong{Ajoutez des contrôles}: @ref{Bar check}, @ref{Octave
+check} et @ref{Barnumber check}. Si vous avez ajouté des contrôles de
+loin en loin, et que vous faites une erreur, vous pourrez la retrouver
+plus rapidement. @qq{De loin en loin}, qu'est-ce à dire ? Cela
+dépend de la complexité de la musique. Pour de la musique très
+simple, peut-être une ou deux fois. Pour de la musique très complexe,
+peut-être à chaque mesure.
+
+@item @strong{Une mesure par ligne de texte}. Si la musique en elle-même ou
+le résultat que vous désirez contient quelque chose de compliqué, il
+est souvent bon de n'écrire qu'une seule mesure par ligne. Économiser
+de la place en tassant huit mesures par ligne, ça ne vaut pas vraiment
+le coup si vous avez à corriger vos fichiers.
+
+@item @strong{Ajoutez des commentaires}. Utilisez soit des
+numéros de mesure (assez souvent), soit des références au contenu
+musical (@q{second thème des violons,} @q{quatrième variation,} etc.).
+Vous pouvez ne pas avoir besoin des commentaires lorsque vous écrivez
+une pièce pour la première fois, mais si vous souhaitez y revenir deux
+ou trois ans plus tard pour changer quelque chose, ou si vous donnez
+le fichier source à un ami, ce sera beaucoup plus difficile de
+déterminer vos intentions ou la manière dont votre fichier est
+structuré si vous n'y avez pas adjoint de commentaires.
+
+@item @strong{Indentez les accolades}. Beaucoup de problèmes
+viennent d'un défaut de parité entre @code{@{} et @code{@}}.
+
+@item @strong{Séparez les retouches de mise en forme} de la musique
+elle-même. Voyez @ref{Saving typing with identifiers and functions} et
+@ref{Style sheets}.
+
+@end itemize
+
@node Typesetting existing music
@subsection Typesetting existing music
-UNTRANSLATED NODE: IGNORE ME
+Si vous saisissez de la musique à partir d'une partition existante,
+c'est-à-dire de la musique déjà écrite,
+
+@itemize @bullet
+
+@item n'entrez qu'un seul système de la partition originale
+à la fois --- mais toujours une seule mesure par ligne de texte ---,
+et vérifiez chaque système lorsqu'il est terminé. Vous pouvez
+utiliser la commande @code{showLastLength} pour accélérer la
+compilation --- voir @ref{Skipping corrected music} ;
+
+@item définissez @code{mBreak = @{\break @}} et insérez
+@code{\mBreak} dans le fichier d'entrée à chaque saut de ligne dans la
+partition originale. Cela facilite la comparaison entre la partition
+originale et la partition de LilyPond. Lorsque vous avez fini de
+relire votre musique, vous pouvez définir @code{mBreak = @{ @}} pour
+enlever tous ces sauts de ligne, et laisser LilyPond placer les sauts
+de ligne selon son propre algorithme.
+
+@end itemize
+
@node Large projects
@subsection Large projects
-UNTRANSLATED NODE: IGNORE ME
+Lorsque l'on travaille sur un gros projet, il devient vital
+de structurer clairement ses fichiers LilyPond.
+
+@itemize @bullet
+
+@item @strong{utilisez un identificateur pour chaque voix},
+avec un minimum de structure dans la définition. La structure de la
+section @code{\score} est la plus susceptible de changer, notamment
+dans une nouvelle version de LilyPond, alors que la définition du
+@code{violon} l'est beaucoup moins.
+
+@example
+violin = \relative c'' @{
+g4 c'8. e16
+@}
+...
+\score @{
+ \new GrandStaff @{
+ \new Staff @{
+ \violin
+ @}
+ @}
+@}
+@end example
+
+@item @strong{Séparez les retouches} des définitions de
+musique. Ce conseil a été vu dans @ref{General suggestions},
+mais pour les gros projets c'est absolument vital. Nous
+pouvons avoir besoin de changer la définition de
+@code{fthenp}, mais dans ce cas nous n'aurons besoin de le faire
+qu'une seule fois, et nous pourrons encore éviter de
+modifier quoi que ce soit à l'intérieur de la définition
+du @code{violon}.
+
+@example
+fthenp = _\markup@{
+ \dynamic f \italic \small @{ 2nd @} \hspace #0.1 \dynamic p @}
+violin = \relative c'' @{
+g4\fthenp c'8. e16
+@}
+@end example
+
+@end itemize
+
@node Saving typing with identifiers and functions
@section Saving typing with identifiers and functions
-UNTRANSLATED NODE: IGNORE ME
+@cindex variables
+@cindex identificateurs
+
+Jusqu'à maintenant, vous avez vu ce type de code :
+
+@lilypond[quote,verbatim,ragged-right]
+hornNotes = \relative c'' { c4 b dis c }
+\score {
+ {
+ \hornNotes
+ }
+}
+@end lilypond
+
+Vous comprendrez combien cela peut être utile pour écrire de la
+musique minimaliste :
+
+@lilypond[quote,verbatim,ragged-right]
+fragA = \relative c'' { a4 a8. b16 }
+fragB = \relative c'' { a8. gis16 ees4 }
+violin = \new Staff { \fragA \fragA \fragB \fragA }
+\score {
+ {
+ \violin
+ }
+}
+@end lilypond
+
+Cependant, vous pouvez aussi utiliser ces identificateurs
+--- aussi connus sous le nom de variables, macros, ou commandes
+(définies par l'utilisateur) --- pour des retouches :
+
+@lilypond[quote,verbatim,ragged-right]
+dolce = \markup{ \italic \bold dolce }
+padText = { \once \override TextScript #'padding = #5.0 }
+fthenp=_\markup{ \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p }
+violin = \relative c'' {
+ \repeat volta 2 {
+ c4._\dolce b8 a8 g a b |
+ \padText
+ c4.^"hi there!" d8 e' f g d |
+ c,4.\fthenp b8 c4 c-. |
+ }
+}
+\score {
+ {
+ \violin
+ }
+\layout{ragged-right=##t}
+}
+@end lilypond
+
+Ces identificateurs sont évidemment utiles pour économiser de la
+frappe. Mais ils peuvent l'être même si vous ne les utilisez qu'une
+seule fois : ils réduisent la complexité. Regardons l'exemple
+précédent sans aucun identificateur. C'est beaucoup plus laborieux à
+lire, et particulièrement la dernière ligne.
+
+@example
+violin = \relative c'' @{
+ \repeat volta 2 @{
+ c4._\markup@{ \italic \bold dolce @} b8 a8 g a b |
+ \once \override TextScript #'padding = #5.0
+ c4.^"hi there!" d8 e' f g d |
+ c,4.\markup@{ \dynamic f \italic \small @{ 2nd @}
+ \hspace #0.1 \dynamic p @} b8 c4 c-. |
+ @}
+@}
+@end example
+
+Jusqu'ici nous avons vu des substitutions statiques : quand LilyPond
+rencontre @code{\padText}, il le remplace par le contenu que nous lui
+avons défini --- c'est-à-dire le contenu à droite de @code{padText=}).
+
+LilyPond gère également des substitutions non-statiques --- vous
+pouvez les voir comme des fonctions.
+
+@lilypond[quote,verbatim,ragged-right]
+padText =
+#(define-music-function (parser location padding) (number?)
+ #{
+ \once \override TextScript #'padding = #$padding
+ #})
+
+\relative c''' {
+ c4^"piu mosso" b a b
+ \padText #1.8
+ c4^"piu mosso" d e f
+ \padText #2.6
+ c4^"piu mosso" fis a g
+}
+@end lilypond
+
+Utiliser les identificateurs est aussi un bon moyen pour vous épargner
+du travail si la syntaxe de LilyPond change un jour --- voir
+@ref{Updating old files}. Si vous avez une seule définition, par
+exemple @code{\dolce}, pour tous vos fichiers (voir @ref{Style
+sheets}), et que la syntaxe change, alors vous n'aurez qu'à mettre à
+jour votre seule définition @code{\dolce}, au lieu de devoir modifier
+chaque fichier @code{.ly}.
+
@node Style sheets
@section Style sheets
-UNTRANSLATED NODE: IGNORE ME
+La sortie que produit LilyPond peut être largement modifiée --- voir
+@ref{Tweaking output} pour plus de détails. Mais que faire si vous
+avez beaucoup de fichiers auxquels vous souhaitez appliquer vos
+retouches ? Ou si vous souhaitez simplement séparer les retouches de
+la musique elle-même ? Rien de plus facile.
+
+Prenons un exemple. Ne vous inquiétez pas si vous ne comprenez pas
+les parties avec tous les @code{#()}. Celles-ci sont expliquées dans
+@ref{Advanced tweaks with Scheme}.
+
+@lilypond[quote,verbatim,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line(#:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
+ \mark \markup { \bold $markp }
+#})
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+Il y a quelques problèmes de chevauchement ; nous allons arranger
+cela en utilisant les techniques de @ref{Moving objects}. On peut
+aussi aussi faire quelque chose pour les définitions de @code{mpdolce}
+et @code{tempoMark}. Elles produisent le résultat que nous désirons,
+mais nous pourrions aussi vouloir les utiliser dans une autre pièce.
+Nous pourrions simplement les copier et les coller au début de chaque
+fichier, mais c'est fastidieux. De plus, cela laisse les définitions
+dans nos fichiers de musique, et je trouve personnellement tous ces
+@code{#()} assez laids. Cachons-les dans un autre fichier :
+
+@example
+%%% enregistrez ceci dans un fichier nommé "definitions.ly"
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line(#:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#@{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
+ \mark \markup @{ \bold $markp @}
+#@})
+@end example
+
+Maintenant, modifions notre musique (enregistrez ce fichier
+sous @file{"musique.ly"}).
+
+@c We have to do this awkward example/lilypond-non-verbatim
+@c because we can't do the \include stuff in the manual.
+
+@example
+\include "definitions.ly"
+
+\relative c'' @{
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+@}
+@end example
+
+@lilypond[quote,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line(#:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
+ \mark \markup { \bold $markp }
+#})
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+C'est mieux, mais effectuons encore quelques retouches. Le glissando
+est peu visible, c'est pourquoi nous allons l'épaissir et le
+rapprocher des têtes de notes. Déplaçons l'indication métronomique
+au-dessus de la clef, au lieu de la laisser au-dessus de la première
+note. Et pour finir, mon professeur de composition déteste les
+chiffrages de mesure en "C", nous allons donc le transformer en "4/4".
+
+Cependant, ne changez pas le fichier @file{musique.ly}. Remplacez le
+fichier @file{definitions.ly} par ceci :
+
+@example
+%%% definitions.ly
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#@{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
+ \mark \markup @{ \bold $markp @}
+#@})
+
+\layout@{
+ \context @{ \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ @}
+ \context @{ \Staff
+ \override TimeSignature #'style = #'numbered
+ @}
+ \context @{ \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ @}
+@}
+@end example
+
+@lilypond[quote,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
+ \mark \markup { \bold $markp }
+#})
+
+\layout{
+ \context { \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ }
+ \context { \Staff
+ \override TimeSignature #'style = #'numbered
+ }
+ \context { \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ }
+}
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+C'est encore mieux ! Mais supposons maintenant que je veuille publier
+cette pièce. Mon professeur de composition n'aime pas les chiffrages
+de mesure en "C", mais moi je les aime bien. Copions l'actuel
+@file{definitions.ly} dans le fichier @file{publication-web.ly}, et
+modifions ce dernier. Puisque la musique est destinée à produire un
+fichier PDF affiché sur écran, nous allons aussi augmenter la taille
+globale de police.
+
+@example
+%%% definitions.ly
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#@{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
+ \mark \markup @{ \bold $markp @}
+#@})
+
+#(set-global-staff-size 23)
+\layout@{
+ \context @{ \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ @}
+ \context @{ \Staff
+ @}
+ \context @{ \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ @}
+@}
+@end example
+
+@lilypond[quote,ragged-right]
+mpdolce = #(make-dynamic-script (markup #:hspace 1 #:translate (cons 5 0)
+ #:line( #:dynamic "mp" #:text #:italic "dolce" )))
+tempoMark = #(define-music-function (parser location markp) (string?)
+#{
+ \once \override Score . RehearsalMark #'self-alignment-X = #left
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
+ \mark \markup { \bold $markp }
+#})
+
+#(set-global-staff-size 23)
+\layout{
+ \context { \Score
+ \override MetronomeMark #'extra-offset = #'(-9 . 0)
+ \override MetronomeMark #'padding = #'3
+ }
+ \context { \Voice
+ \override Glissando #'thickness = #3
+ \override Glissando #'gap = #0.1
+ }
+}
+
+\relative c'' {
+ \tempo 4=50
+ a4.\mpdolce d8 cis4--\glissando a | b4 bes a2
+ \once \override Score.RehearsalMark #'padding = #2.0
+ \tempoMark "Poco piu mosso"
+ cis4.\< d8 e4 fis | g8(\! fis)-. e( d)-. cis2
+}
+@end lilypond
+
+Il ne nous reste plus qu'à remplacer @code{\include "definitions.ly"}
+par @code{\include "web-publish.ly"} dans notre fichier de musique.
+
+Il est possible, bien sûr, de rendre cela encore plus pratique. Nous
+pourrions créer un fichier @file{definitions.ly} qui ne contiendrait
+que les définitions de @code{mpdolce} et de @code{tempoMark}, un
+fichier @file{publication-web.ly} qui ne contiendrait que la section
+@code{layout} décrite ci-dessus et un fichier @file{university.ly} qui
+ne contiendrait que les retouches pour produire le résultat que mon
+professeur préfère. Le début du fichier @file{music.ly} ressemblerait
+alors à
+
+@example
+\include "definitions.ly"
+
+%%% Décommentez seulement une de ces deux lignes !
+\include "web-publish.ly"
+%\include "university.ly"
+@end example
+
+Cette approche peut être utile même si vous ne produisez qu'un seul
+jeu de partitions. J'utilise une demi-douzaine de fichiers de
+@qq{feuille de style} pour mes projets. Je commence chaque fichier de
+musique musical par @code{\include "../global.ly"} qui contient :
+
+@example
+%%% global.ly
+\version "2.9.13"
+#(ly:set-option 'point-and-click #f)
+\include "../init/init-defs.ly"
+\include "../init/init-mise-en-page.ly"
+\include "../init/init-en-tetes.ly"
+\include "../init/init-papier.ly"
+@end example
@node Updating old files
@section Updating old files
-UNTRANSLATED NODE: IGNORE ME
+La syntaxe de LilyPond change de temps en temps. Ces changements de
+syntaxe du langage d'entrée accompagnent les améliorations du
+logiciel. Ces changements sont parfois destinés à rendre les fichiers
+plus faciles à lire et à écrire, ou permettent d'intégrer de nouvelles
+fonctionnalités.
+
+LilyPond est fourni avec un utilitaire qui facilite cette mise à
+jour : @code{convert-ly}. Pour savoir comment utiliser ce programme,
+voir @ref{Updating files with convert-ly}.
+
+Malheureusement, @code{convert-ly} ne peut pas réaliser tous les
+changements. Il s'occupe des changements qui ne requièrent qu'une
+simple substitution de texte --- comme @code{raggedright} devenant
+@code{ragged-right} ---, les autres étant trop compliqués à effectuer.
+Les changements de syntaxe qui ne sont pas gérés par @code{convert-ly}
+sont énumérés dans @ref{Updating files with convert-ly}.
+
+Par exemple, dans les versions 2.4 et antérieures de LilyPond,
+les accents et les lettres non anglaises étaient entrées en
+utilisant LaTeX --- par exemple, @samp{No\"el}. À partir de la
+version 2.6, le caratère @samp{ë} doit être entré directement
+dans le fichier LilyPond comme caractère UTF-8.
+@code{convert-ly} ne peut pas changer tous les caractères
+LaTeX en caractères UTF-8 ; vous devez mettre à jour vos vieux
+fichiers LilyPond manuellement.
+
+
@node Troubleshooting (taking it all apart)
@section Troubleshooting (taking it all apart)
-UNTRANSLATED NODE: IGNORE ME
+Tôt ou tard, vous écrirez un fichier que LilyPond ne peut pas
+compiler. Les messages que LilyPond affiche peuvent vous aider à
+trouver l'erreur, mais dans beaucoup de cas vous aurez besoin de faire
+quelques recherches pour déterminer la source du problème.
+
+Pour ce faire, les outils les plus puissants sont le commentaire de
+fin de ligne, indiqué par @code{%}, et le commentaire multilignes (ou
+bloc de commentaire), indiqué par @code{%@{ ... %@}}. Si vous ne
+pouvez localiser le problème, commencez par mettre en commentaire de
+grandes parties de votre fichier d'entrée. Après avoir mis en
+commentaire une section, essayez de compiler à nouveau. Si cela
+fonctionne, c'est que le problème se situe dans cette partie du
+fichier. Si cela ne fonctionne pas, continuez à mettre en commentaire
+d'autres sections, jusqu'à ce que vous ayez quelque chose qui compile.
+
+Dans un cas extrême, vous pourriez arriver à
+
+@example
+\score @{
+ <<
+ % \melodie
+ % \harmonie
+ % \basse
+ >>
+ \layout@{@}
+@}
+@end example
+
+@noindent
+c'est-à-dire un fichier sans aucune musique.
+
+Si cela arrive, ne vous découragez pas. Décommentez un peu, la partie
+de basse par exemple, et voyez si ça fonctionne. Si ce n'est pas le
+cas, placez en commentaire toute la partie de basse, mais laissez
+@code{\basse} décommenté dans le bloc @code{\score}.
+
+@example
+basse = \relative c' @{
+%@{
+ c4 c c c
+ d d d d
+%@}
+@}
+@end example
+
+Maintenant commencez à décommenter petit à petit le partie de
+@code{basse} jusqu'à ce que vous localisiez la ligne qui pose
+problème.
+
+Une autre technique de déboguage très utile est la construction
+@iftex
+de @ref{Minimal examples}.
+@end iftex
+@ifnottex
+d'@ref{Minimal examples}.
+@end ifnottex
+
+
+@node Minimal examples
+@section Minimal examples
+
+Un exemple minimal est un exemple de code aussi court que possible.
+De tels exemples sont bien plus compréhensibles que des exemple
+longs. Les exemples minimaux sont utilisés pour
+
+@itemize
+@item les rapports de bogue,
+@item les demandes d'aide sur les listes de diffusion,
+@item un ajout à
+@uref{http://lsr@/.dsi@/.unimi/2.it/,LilyPond Snippet Repository}.
+@end itemize
+
+Pour construire un exemple minimal, la règle est très simple : enlevez
+tout ce qui n'est pas nécessaire. Il est préférable de commenter les
+lignes non nécessaires plutôt que de les effacer : ainsi, si vous vous
+apercevez que certaines étaient @emph{réellement} nécessaires, vous
+pouvez les décommenter au lieu de les resaisir.
+
+Il y a deux exceptions à cette règle du strict nécessaire :
+
+@itemize
+@item incluez le numéro de @code{\version},
+@item si possible, utilisez @code{\paper@{ ragged-right=##t @}} au
+début de votre exemple.
+@end itemize
+Tout l'intérêt d'un exemple minimal réside dans sa facilité de lecture
+:
+@itemize
+@item évitez d'utiliser des notes, armures ou métriques compliquées, à
+moins que vous vouliez montrer quelque chose en rapport avec
+celles-ci,
+@item n'utilisez pas de commandes @code{\override} sauf si elles font
+l'intérêt de l'exemple.
+@end itemize
* Lines should be less than 80 characters long.
+* Use @q instead of `...' and @qq instead of ``...''. The latter macro
+ should be used with care since we use `...' as the default quoting
+ throughout the manual, except for things related to direct speech.
+
%%%%%
HINTS FOR TECHNICAL WRITING STYLE
@cindex whole rests for a full measure
@funindex R
-Rests for one full measure (or many bars) are entered using `@code{R}'. It
+Rests for one full measure (or many bars) are entered using @samp{R}. It
is specifically meant for full bar rests and for entering parts: the rest
can expand to fill a score with rests, or it can be printed as a single
multi-measure rest. This expansion is controlled by the property
An @code{R} spanning a single measure is printed as either a whole rest
or a breve, centered in the measure regardless of the time signature.
-If there are only a few measures of rest, LilyPond prints ``church rests''
+If there are only a few measures of rest, LilyPond prints @qq{church rests}
(a series of rectangles) in the staff. To replace that with a simple
rest, use @code{MultiMeasureRest.expand-limit}.
@end lilypond
@noindent
-The letter@tie{}`I' is skipped in accordance with engraving traditions.
-If you wish to include the letter `I', then use
+The letter@tie{}@q{I} is skipped in accordance with engraving traditions.
+If you wish to include the letter @q{I}, then use
@example
\set Score.markFormatter = #format-mark-alphabet
@node Ottava brackets
@subsection Ottava brackets
-`Ottava' brackets introduce an extra transposition of an octave for
+@q{Ottava} brackets introduce an extra transposition of an octave for
the staff. They are created by invoking the function
@code{set-octavation}
specified twice (once in each part). Stem, slur, and tie directions are
set automatically, depending whether there is a solo or unisono. The
first part (with context called @code{one}) always gets up stems, and
-`Solo', while the second (called @code{two}) always gets down stems and
-`Solo II'.
+@q{Solo}, while the second (called @code{two}) always gets down stems and
+@q{Solo II}.
If you just want the merging parts, and not the textual markings, you
may set the property @code{printPartCombineTexts} to false
@cindex Hiding staves
In orchestral scores, staff lines that only have rests are usually
-removed; this saves some space. This style is called `French Score'.
+removed; this saves some space. This style is called @q{French Score}.
For @internalsref{Lyrics},
@internalsref{ChordNames} and @internalsref{FiguredBass}, this is
switched on by default. When the lines of these contexts turn out
Quoting grace notes is broken and can even cause LilyPond to crash.
+Quoting nested triplets may result in poor notation.
+
+
@seealso
In this manual: @ref{Instrument transpositions}.
In the 20th century, composers have greatly expanded the musical
vocabulary. With this expansion, many innovations in musical notation
-have been tried. The book ``Music Notation in the 20th century'' by
+have been tried. The book @qq{Music Notation in the 20th century} by
Kurt Stone gives a comprehensive overview (see @ref{Literature
list}).
@node Polymetric notation
@subsection Polymetric notation
+@cindex double time signatures
+@cindex signatures, polymetric
+@cindex polymetric signatures
+@cindex meter, polymetric
+
Double time signatures are not supported explicitly, but they can be
faked. In the next example, the markup for the time signature is
created with a markup text. This markup text is inserted in the
@cindex note heads, special
Different noteheads are used by various instruments for various
-meanings -- crosses are used for ``parlato'' with vocalists, stopped
+meanings -- crosses are used for @qq{parlato} with vocalists, stopped
notes on guitar; diamonds are used for harmonics on string instruments,
etc. There is a shorthand (@code{\harmonic}) for diamond shapes; the
other notehead styles are produced by tweaking the property
@cindex easy notation
@cindex Hal Leonard
-The `easy play' note head includes a note name inside the head. It is
+The @q{easy play} note head includes a note name inside the head. It is
used in music for beginners
@lilypond[quote,ragged-right,verbatim,fragment,staffsize=26]
@menu
* Pitches::
* Rhythms::
-* Multiple notes at once::
+* Polyphony::
* Staff notation::
* Connecting notes::
* Expressive marks::
* Accidentals::
* Cautionary accidentals::
* Micro tones::
-* Notes names in other languages::
+* Note names in other languages::
* Relative octaves::
* Octave check::
* Transpose::
@funindex ,
The optional octave specification takes the form of a series of
-single quote (`@code{'}') characters or a series of comma
-(`@code{,}') characters. Each @code{'} raises the pitch by one
+single quote (@samp{'}) characters or a series of comma
+(@samp{,}) characters. Each @code{'} raises the pitch by one
octave; each @code{,} lowers the pitch by an octave.
@lilypond[quote,ragged-right,fragment,verbatim]
E-natural, and an F-natural,'' regardless of the key
signature. For more information about the distinction between
musical content and the presentation of that content, see
-@ref{More about pitches}.
+@ref{Accidentals and key signatures}.
@lilypond[fragment,quote,ragged-right,verbatim,relative]
\key d \major
can be forced by adding an exclamation mark @code{!}
after the pitch. A cautionary accidental
(i.e., an accidental within parentheses) can be obtained by adding the
-question mark `@code{?}' after the pitch. These extra accidentals
+question mark @samp{?} after the pitch. These extra accidentals
can be used to produce natural signs, too.
@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
standard.
-@node Notes names in other languages
-@subsection Notes names in other languages
+@node Note names in other languages
+@subsection Note names in other languages
There are predefined sets of note names for various other languages.
To use them, include the language specific init file. For
@code{\transpose} may also be used to input written notes for a
transposing instrument. Pitches are normally entered into LilyPond
-in C (or ``concert pitch''), but they may be entered in another
+in C (or @qq{concert pitch}), but they may be entered in another
key. For example, when entering music for a B-flat trumpet which
begins on concert D, one would write
@funindex \skip
@funindex s
-An invisible rest (also called a `skip') can be entered like a note
-with note name `@code{s}' or with @code{\skip @var{duration}}
+An invisible rest (also called a @q{skip}) can be entered like a note
+with note name @samp{s} or with @code{\skip @var{duration}}
@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
a4 a4 s4 a4 \skip 1 a4
@funindex .
-To obtain dotted note lengths, simply add a dot (`@code{.}') to
+To obtain dotted note lengths, simply add a dot (@samp{.}) to
the number. Double-dotted notes are produced in a similar way.
@lilypond[quote,ragged-right,fragment,verbatim]
@subsection Scaling durations
You can alter the length of duration by a fraction @var{N/M}
-appending `@code{*}@var{N/M}' (or `@code{*}@var{N}' if @var{M=1}). This
+appending @q{@code{*}@var{N/M}} (or @q{@code{*}@var{N}} if @var{M=1}). This
will not affect the appearance of the notes or rests produced.
In the following example, the first three notes take up exactly two
@funindex |
Bar checks help detect errors in the durations. A bar check is
-entered using the bar symbol, `@code{|}'. Whenever it is encountered
+entered using the bar symbol, @samp{|}. Whenever it is encountered
during interpretation, it should fall on a measure boundary. If it
does not, a warning is printed. In the next example, the second bar
check will signal an error
Program reference: @internalsref{Completion_heads_engraver}.
-@node Multiple notes at once
-@section Multiple notes at once
+@node Polyphony
+@section Polyphony
Polyphony in music refers to having more than one voice occurring in
a piece of music. Polyphony in LilyPond refers to having more than
@end lilypond
The separator causes @internalsref{Voice} contexts@footnote{Polyphonic
-voices are sometimes called ``layers'' in other notation packages}
+voices are sometimes called @qq{layers} in other notation packages}
@cindex layers
to be instantiated. They bear the names @code{"1"}, @code{"2"}, etc. In
each of these contexts, vertical direction of slurs, stems, etc., is set
Here, @var{type} should be @code{\major} or @code{\minor} to get
@var{pitch}-major or @var{pitch}-minor, respectively. You may also
-use the standard mode names (also called ``church modes''): @code{\ionian},
+use the standard mode names (also called @qq{church modes}): @code{\ionian},
@code{\locrian}, @code{\aeolian}, @code{\mixolydian}, @code{\lydian},
@code{\phrygian}, and @code{\dorian}.
Accidentals and key signatures often confuse new users, because
unaltered notes get natural signs depending on the key signature. For
-more information, see @ref{Accidentals} or @ref{More about pitches}.
+more information, see @ref{Accidentals} or @ref{Accidentals and key signatures}.
@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
\key g \major
The property @code{measurePosition} contains a rational number
indicating how much of the measure has passed at this point. Note
that this is a negative number; @code{\partial 4} is internally
-translated to mean ``there is a quarter note left in the bar''.
+translated to mean @qq{there is a quarter note left in the bar}.
@refbugs
@cindex adjusting staff symbol
Notes, dynamic signs, etc., are grouped
-with a set of horizontal lines, called a staff (plural `staves'). In
+with a set of horizontal lines, called a staff (plural @q{staves}). In
LilyPond, these lines are drawn using a separate layout object called
@code{staff symbol}.
A tie connects two adjacent note heads of the same pitch. The tie in
effect extends the length of a note. Ties should not be confused with
slurs, which indicate articulation, or phrasing slurs, which indicate
-musical phrasing. A tie is entered using the tilde symbol `@code{~}'
+musical phrasing. A tie is entered using the tilde symbol @samp{~}
@lilypond[quote,ragged-right,fragment,verbatim]
e' ~ e' <c' e' g'> ~ <c' e' g'>
Unlike @code{\acciaccatura} and @code{\appoggiatura}, the
@code{\grace} command does not start a slur.
-Internally, timing for grace notes is done using a second, `grace'
+Internally, timing for grace notes is done using a second, @q{grace}
timing. Every point in time consists of two rational numbers: one
denotes the logical time, one denotes the grace timing. The above
example is shown here with timing tuples
c1 \afterGrace d1 { c16[ d] } c4
@end lilypond
-This will put the grace notes after a ``space'' lasting 3/4 of the
+This will put the grace notes after a @qq{space} lasting 3/4 of the
length of the main note. The fraction 3/4 can be changed by setting
@code{afterGraceFraction}, ie.
@node Repeat syntax
@subsection Repeat syntax
+@cindex volta
+@cindex prima volta
+@cindex seconda volta
+
LilyPond has one syntactic construct for specifying different types of
repeats. The syntax is
In the following example, the first ending is not a complete
bar (it only had 3 beats). The beginning of the second ending
-contains the 4th beat from the first ending. This ``extra''
+contains the 4th beat from the first ending. This @qq{extra}
beat in the second ending is due to the first time ending,
and has nothing to do with the @code{\partial} at the
beginning of the example.
@funindex tremoloFlags
Tremolo marks can be printed on a single note by adding
-`@code{:}[@var{number}]' after the note. The number indicates the
+@q{@code{:}[@var{number}]} after the note. The number indicates the
duration of the subdivision, and it must be at least 8. A
@var{length} value of 8 gives one line across the note stem. If the
length is omitted, the last value (stored in @code{tremoloFlags}) is
The purpose of LilyPond's design is to provide the finest output
quality as a default. Nevertheless, it may happen that you need to
change this default layout. The layout is controlled through a large
-number of proverbial ``knobs and switches.'' This chapter does not
+number of proverbial @qq{knobs and switches.} This chapter does not
list each and every knob. Rather, it outlines what groups of controls
are available and explains how to lookup which knob to use for a
particular effect.
That manual
lists all different variables, functions and options available in
LilyPond. It is written as a HTML document, which is available
-@uref{http://@/lilypond@/.org/@/doc/@/v2.8/@/Documentation/@/user/@/
-lilypond@/-internals/,on@/-line},
+@c leave the @uref as one long line.
+@uref{http://@/lilypond@/.org/@/doc/@/stable/@/Documentation/@/user/@/lilypond@/-internals/,on@/-line},
but is also included with the LilyPond documentation package.
There are four areas where the default settings may be changed:
@item @code{modern-cautionary}
@funindex modern-cautionary
-This rule is similar to @code{modern}, but the ``extra'' accidentals
+This rule is similar to @code{modern}, but the @qq{extra} accidentals
(the ones not typeset by @code{default}) are typeset as cautionary
accidentals. They are printed in reduced size or with parentheses
@lilypond[quote,ragged-right,fragment,verbatim]
@item no-reset
@funindex no-reset accidental style
This is the same as @code{default} but with accidentals lasting
-``forever'' and not only until the next measure
+@qq{forever} and not only until the next measure
@lilypond[quote,ragged-right,fragment,verbatim,relative=1]
#(set-accidental-style 'no-reset)
c1 cis cis c
Contexts are hierarchical, so if a bigger context was specified, for
example @context{Staff}, then the change would also apply to all
@context{Voice}s in the current stave. The change is applied
-`on-the-fly', during the music, so that the setting only affects the
+@q{on-the-fly}, during the music, so that the setting only affects the
second group of eighth notes.
@funindex \unset
Notation contexts (like @code{Score} and @code{Staff}) not only
store properties,
-they also contain plug-ins called ``engravers'' that create notation
+they also contain plug-ins called @qq{engravers} that create notation
elements. For example, the @code{Voice} context contains a
@code{Note_head_engraver} and the @code{Staff} context contains a
@code{Key_signature_engraver}.
Here @var{name} is the name of a graphical object, like @code{Stem} or
@code{NoteHead}, and @var{property} is an internal variable of the
-formatting system (`grob property' or `layout property'). The latter is a
+formatting system (@q{grob property} or @q{layout property}). The latter is a
symbol, so it must be quoted. The subsection @ref{Constructing a
tweak} explains what to fill in for @var{name}, @var{property}, and
@var{value}. Here we only discuss the functionality of this command.
\revert Staff.Stem #'thickness
@end example
-Some tweakable options are called ``subproperties'' and reside inside
+Some tweakable options are called @qq{subproperties} and reside inside
properties. To tweak those, use commands of the form
@c leave this as a long long
@item a sensible value: here @code{3.0}.
@end itemize
-Some tweakable options are called ``subproperties'' and reside inside
+Some tweakable options are called @qq{subproperties} and reside inside
properties. To tweak those, use commands in the form
@example
Clicking any of the links will take you to the page of the respective
object interface. Each interface has a number of properties. Some of
-them are not user-serviceable (``Internal properties''), but others
+them are not user-serviceable (@qq{Internal properties}), but others
can be modified.
We have been talking of @emph{the} @code{Fingering} object, but actually it
does not amount to much. The initialization file (see
@ref{Default files})
-@file{scm/@/define@/-grobs@/.scm} shows the soul of the `object',
+@file{scm/@/define@/-grobs@/.scm} shows the soul of the @q{object},
@example
(Fingering
There is a special type of context property: the element
description. These properties are named in @code{StudlyCaps}
(starting with capital letters). They contain the
-``default settings'' for said graphical object as an
+@qq{default settings} for said graphical object as an
association list. See @file{scm/@/define@/-grobs@/.scm}
to see what kind of settings there are. Element descriptions
may be modified with @code{\override}.
@uref{http://@/lilypond@/.org,website} for more details.
These are separate programs from lilypond itself, and are run
-on the command-line. By ``command-line'', we mean the command
+on the command-line. By @qq{command-line}, we mean the command
line in the operating system. Windows users
-might be more familiar with the terms ``DOS shell'' or
-``command shell''; OSX users might be more familiar with the
-terms ``terminal'' or ``console''. OSX users should also
+might be more familiar with the terms @qq{DOS shell} or
+@qq{command shell}; OSX users might be more familiar with the
+terms @qq{terminal} or @qq{console}. OSX users should also
consult @ref{Notes for the MacOS X app}.
Describing how to use
midi2ly [@var{option}]@dots{} @var{midi-file}
@end example
-Note that by ``command-line'', we mean the command line of the
+Note that by @qq{command-line}, we mean the command line of the
operating system. See @ref{Converting from other formats} for
more information about this.
etf2ly [@var{option}]@dots{} @var{etf-file}
@end example
-Note that by ``command-line'', we mean the command line of the
+Note that by @qq{command-line}, we mean the command line of the
operating system. See @ref{Converting from other formats} for
more information about this.
@command{musicxml2ly} extracts the notes from part-wise MusicXML
files, and writes it to a .ly file. It is invoked from the command-line.
-Note that by ``command-line'', we mean the command line of the
+Note that by @qq{command-line}, we mean the command line of the
operating system. See @ref{Converting from other formats} for
more information about this.
%%LY voices \set autoBeaming = ##f
@end example
-This will cause the text following the keyword ``voices'' to be inserted
+This will cause the text following the keyword @qq{voices} to be inserted
into the current voice of the LilyPond output file.
Similarly,
%%LY slyrics more words
@end example
-will cause the text following the ``slyrics'' keyword to be inserted
+will cause the text following the @qq{slyrics} keyword to be inserted
into the current line of lyrics.
@refbugs
-The ABC standard is not very ``standard''. For extended features
+The ABC standard is not very @qq{standard}. For extended features
(e.g., polyphonic music) different conventions exist.
Multiple tunes in one file cannot be converted.
credit for their work, while not being considered responsible for
modifications made by others.
-This License is a kind of ``copyleft'', which means that derivative
+This License is a kind of @qq{copyleft}, which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
-under the terms of this License. The ``Document'', below, refers to any
+under the terms of this License. The @qq{Document}, below, refers to any
such manual or work. Any member of the public is a licensee, and is
-addressed as ``you''.
+addressed as @qq{you}.
-A ``Modified Version'' of the Document means any work containing the
+A @qq{Modified Version} of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
-A ``Secondary Section'' is a named appendix or a front-matter section of
+A @qq{Secondary Section} is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
commercial, philosophical, ethical or political position regarding
them.
-The ``Invariant Sections'' are certain Secondary Sections whose titles
+The @qq{Invariant Sections} are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.
-The ``Cover Texts'' are certain short passages of text that are listed,
+The @qq{Cover Texts} are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.
-A ``Transparent'' copy of the Document means a machine-readable copy,
+A @qq{Transparent} copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
to text formatters. A copy made in an otherwise Transparent file
format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy that is
-not ``Transparent'' is called ``Opaque''.
+not @qq{Transparent} is called @qq{Opaque}.
Examples of suitable formats for Transparent copies include plain
@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
and the machine-generated @acronym{HTML} produced by some word
processors for output purposes only.
-The ``Title Page'' means, for a printed book, the title page itself,
+The @qq{Title Page} means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
-formats which do not have any title page as such, ``Title Page'' means
+formats which do not have any title page as such, @qq{Title Page} means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
Include an unaltered copy of this License.
@item
-Preserve the section entitled ``History'', and its title, and add to
+Preserve the section entitled @qq{History}, and its title, and add to
it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
-there is no section entitled ``History'' in the Document, create one
+there is no section entitled @qq{History} in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
-it was based on. These may be placed in the ``History'' section.
+it was based on. These may be placed in the @qq{History} section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
@item
-In any section entitled ``Acknowledgments'' or ``Dedications'',
+In any section entitled @qq{Acknowledgments} or @qq{Dedications},
preserve the section's title, and preserve in the section all the
substance and tone of each of the contributor acknowledgments
and/or dedications given therein.
or the equivalent are not considered part of the section titles.
@item
-Delete any section entitled ``Endorsements''. Such a section
+Delete any section entitled @qq{Endorsements}. Such a section
may not be included in the Modified Version.
@item
-Do not retitle any existing section as ``Endorsements''
+Do not retitle any existing section as @qq{Endorsements}
or to conflict in title with any Invariant Section.
@end enumerate
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
-You may add a section entitled ``Endorsements'', provided it contains
+You may add a section entitled @qq{Endorsements}, provided it contains
nothing but endorsements of your Modified Version by various
parties---for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
-In the combination, you must combine any sections entitled ``History''
+In the combination, you must combine any sections entitled @qq{History}
in the various original documents, forming one section entitled
-``History''; likewise combine any sections entitled ``Acknowledgments'',
-and any sections entitled ``Dedications''. You must delete all sections
-entitled ``Endorsements.''
+@qq{History}; likewise combine any sections entitled @qq{Acknowledgments},
+and any sections entitled @qq{Dedications}. You must delete all sections
+entitled @qq{Endorsements.}
@item
COLLECTIONS OF DOCUMENTS
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version
of the Document, provided no compilation copyright is claimed for the
-compilation. Such a compilation is called an ``aggregate'', and this
+compilation. Such a compilation is called an @qq{aggregate}, and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they
are not themselves derivative works of the Document.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
-License ``or any later version'' applies to it, you have the option of
+License @qq{or any later version} applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
@end group
@end smallexample
-If you have no Invariant Sections, write ``with no Invariant Sections''
+If you have no Invariant Sections, write @qq{with no Invariant Sections}
instead of saying which ones are invariant. If you have no
-Front-Cover Texts, write ``no Front-Cover Texts'' instead of
-``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+Front-Cover Texts, write @qq{no Front-Cover Texts} instead of
+@qq{Front-Cover Texts being @var{list}}; likewise for Back-Cover Texts.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
@refbugs
Dynamics are not centered, but workarounds do exist. See the
-``piano centered dynamics'' template in @ref{Piano templates}.
+@qq{piano centered dynamics} template in @ref{Piano templates}.
@cindex cross staff stem
@cindex stem, cross staff
b g \sustainUp a \sustainDown \bar "|."
@end lilypond
-The default `*Ped.' style for sustain and damper pedals corresponds to
+The default @q{*Ped.} style for sustain and damper pedals corresponds to
style @code{#'text}. The sostenuto pedal uses @code{mixed} style by
default.
@lilypond[quote,fragment,verbatim]
\chordmode { e1:m e1:7 e1:m7 }
@end lilypond
-The first number following the root is taken to be the `type' of the
+The first number following the root is taken to be the @q{type} of the
chord, thirds are added to the root until it reaches the specified
number
@lilypond[quote,fragment,verbatim]
@item chordRootNamer
The root of a chord is usually printed as a letter with an optional
alteration. The transformation from pitch to letter is done by this
-function. Special note names (for example, the German ``H'' for a
+function. Special note names (for example, the German @qq{H} for a
B-chord) can be produced by storing a new function in this property.
@funindex chordNoteNamer
@funindex chordPrefixSpacer
@item chordPrefixSpacer
-The ``m'' for minor chords is usually printed right after the root of
+The @qq{m} for minor chords is usually printed right after the root of
the chord. By setting @code{chordPrefixSpacer}, you can fix a spacer
-between the root and ``m''. The spacer is not used when the root
+between the root and @qq{m}. The spacer is not used when the root
is altered.
@end table
@menu
* Setting simple songs::
* Entering lyrics::
-* Hyphens and extenders::
+* Hyphens and extenders::
* The Lyrics context::
* Melismata::
* Another way of entering lyrics::
\relative { c2 e4 g2 e4 }
\addlyrics { gran- de_a- mi- go }
\addlyrics { pu- "ro y ho-" nes- to }
-\addlyrics { pu- ro~yho- nes- to }
+\addlyrics { pu- ro~y~ho- nes- to }
@end lilypond
The lyric ties is implemented with the Unicode character U+203F, so be
@code{?}, @code{!}, @code{:}, @code{'}, the control characters @code{^A}
through @code{^F}, @code{^Q} through @code{^W}, @code{^Y}, @code{^^},
any 8-bit character with ASCII code over 127, or a two-character
-combination of a backslash followed by one of @code{`}, @code{'},
+combination of a backslash followed by one of @code{@q{}, @code{}},
@code{"}, or @code{^}.
To define indentifiers containing lyrics, the function @code{lyricmode}
@cindex hyphens
-Centered hyphens are entered as `@code{--}' between syllables.
+Centered hyphens are entered as @samp{--} between syllables.
The hyphen will have variable length depending on the space between
the syllables and it will be centered between the syllables.
When a lyric is sung over many notes (this is called a melisma), this is
indicated with a horizontal line centered between a syllable and the
next one. Such a line is called an extender line, and it is entered as
-`@code{__}'.
+@samp{__}.
In tighly engraved music, hyphens can be removed. Whether this
happens can be controlled with the @code{minimum-distance} (minimum
@end lilypond
-The @code{ignoreMelismata} applies to the syllable ``fas'', so it
-should be entered before ``go''.
+The @code{ignoreMelismata} applies to the syllable @qq{fas}, so it
+should be entered before @qq{go}.
The reverse is also possible: making a lyric line slower than the
standard. This can be achieved by insert @code{\skip}s into the
@end lilypond
@noindent
-the text for the first stanza is set to a melody called ``lahlah'',
+the text for the first stanza is set to a melody called @qq{lahlah},
@example
\new Lyrics \lyricsto "lahlah" @{
The second stanza initially is set to the @code{lahlah} context, but
-for the syllable ``ran'', it switches to a different melody.
+for the syllable @qq{ran}, it switches to a different melody.
This is achieved with
@example
\set associatedVoice = alternative
Here, @code{alternative} is the name of the @code{Voice} context
containing the triplet.
-Again, the command must be one syllable too early, before ``Ty'' in
+Again, the command must be one syllable too early, before @qq{Ty} in
this case.
@example
@node More about stanzas
@subsection More about stanzas
+@c what's this doing here?
@cindex phrasing, in lyrics
-
@cindex stanza number
-@cindex singer's names
-@cindex name of singer
+@subsubsection Adding stanza numbers
Stanza numbers can be added by setting @code{stanza}, e.g.,
}
@end lilypond
-These numbers are put just before the start of first syllable.
+@noindent
+These numbers are put just before the start of the first syllable.
+
+
+@subsubsection Adding dynamics marks
+
+Stanzas differing in loudness may be indicated by putting a
+dynamics mark before each stanza. In Lilypond, everthing coming in
+front of a stanza goes into the @code{StanzaNumber} object; dynamics marks
+are no different. For technical reasons, you have to set the stanza
+outside @code{\lyricmode}:
+
+@lilypond[quote,ragged-right,verbatim]
+text = {
+ \set stanza = \markup { \dynamic "ff" "1. " }
+ \lyricmode {
+ Big bang
+ }
+}
+
+<<
+ \new Voice = "tune" {
+ \time 3/4
+ g'4 c'2
+ }
+\new Lyrics \lyricsto "tune" \text
+>>
+@end lilypond
+
+@cindex singer name
+@cindex name of singer
+@subsubsection Adding singer names
+
+Names of singers can also be added. They are printed at the start of
+the line, just like instrument names. They are created by setting
+@code{vocalName}. A short version may be entered as @code{shortVocalName}.
+
+@lilypond[fragment,ragged-right,quote,verbatim,relative=2]
+\new Voice {
+ \time 3/4 g2 e4 a2 f4 g2.
+} \addlyrics {
+ \set vocalName = "Bert "
+ Hi, my name is Bert.
+} \addlyrics {
+ \set vocalName = "Ernie "
+ Oh, che -- ri, je t'aime
+}
+@end lilypond
+
+
+@subsubsection Printing stanzas at the end
Sometimes it is appropriate to have one stanza set
to the music, and the rest added in verse form at
@end lilypond
-Names of singers can also be added. They are printed at the start of
-the line, just like instrument names. They are created by setting
-@code{vocalName}. A short version may be entered as @code{shortVocalName}.
-
-
-@lilypond[fragment,ragged-right,quote,verbatim,relative=2]
-\new Voice {
- \time 3/4 g2 e4 a2 f4 g2.
-} \addlyrics {
- \set vocalName = "Bert "
- Hi, my name is Bert.
-} \addlyrics {
- \set vocalName = "Ernie "
- Oh, che -- ri, je t'aime
-}
-@end lilypond
-
+@subsubsection Printing stanzas at the end in multiple columns
When a piece of music has many verses, they are often printed in
multiple columns across the page. An outdented verse number often
examples, and that might get them more involved in the docs. -gp
@end ignore
-``Parlato'' is spoken without pitch but still with rhythm; it is
+@qq{Parlato} is spoken without pitch but still with rhythm; it is
notated by cross noteheads. This is demonstrated in
@ref{Special noteheads}.
@emph{Historic style} means ``as was typeset or written in historic
editions (other than those of Petrucci)''.
-@emph{Editio XXX style} means ``as is/was printed in Editio XXX''.
+@emph{Editio XXX style} means @qq{as is/was printed in Editio XXX}.
Petrucci used C clefs with differently balanced left-side vertical
beams, depending on which staff line it is printed.
@cindex custos
@cindex custodes
-A @emph{custos} (plural: @emph{custodes}; Latin word for `guard') is a
+A @emph{custos} (plural: @emph{custodes}; Latin word for @q{guard}) is a
symbol that appears at the end of a staff. It anticipates the pitch
of the first note(s) of the following line thus helping the performer
to manage line breaks during performance.
@cindex finalis
A @emph{divisio} (plural: @emph{divisiones}; Latin word for
-`division') is a staff context symbol that is used to structure
+@q{division}) is a staff context symbol that is used to structure
Gregorian music into phrases and sections. The musical meaning of
@emph{divisio minima}, @emph{divisio maior}, and @emph{divisio maxima}
can be characterized as short, medium, and long pause, somewhat like
In European music from before about 1600, singers were often expected
to chromatically alter notes at their own initiative. This is called
-``Musica Ficta''. In modern transcriptions, these accidentals are
+@qq{Musica Ficta}. In modern transcriptions, these accidentals are
usually printed over the note.
@cindex Accidental, musica ficta
In spacing, the distribution of space should reflect the durations
between notes. However, many modern scores adhere to the durations
with mathematical precision, which leads to poor results. In the next
-example a motive is printed twice : once using exact mathematical
+example a motive is printed twice: once using exact mathematical
spacing, and once with corrections. Can you spot which fragment is
which?
In this situation, the accidentals and staff are shared, but the stems,
slurs, beams, etc., are private to each voice. Hence, engravers should
be grouped. The engravers for note heads, stems, slurs, etc., go into a
-group called `Voice context', while the engravers for key, accidental,
-bar, etc., go into a group called `Staff context'. In the case of
+group called @q{Voice context}, while the engravers for key, accidental,
+bar, etc., go into a group called @q{Staff context}. In the case of
polyphony, a single Staff context contains more than one Voice context.
Similarly, multiple Staff contexts can be put into a single Score
context. The Score context is the top level notation context.
a list of color names, and the Feta font.
@item
-@emph{@ref{Example templates}}
-provides templates of LilyPond pieces. Just cut and paste a
+@emph{@ref{Templates}}
+of LilyPond pieces. Just cut and paste a
template into a file, add notes, and you're done!
@item
initialization and example files. Throughout this manual, we refer to
input files relative to the top-directory of the source archive. For
example, @file{input/@/test/@/bla@/.ly} may refer to the file
-@file{lilypond@/-2.8.0/@/input/@/test/@/bla@/.ly}. On binary packages
+@file{lilypond@/2.x.y/@/input/@/test/@/bla@/.ly}. On binary packages
for the Unix platform, the documentation and examples can typically be
found somewhere below @file{/usr/@/share/@/doc/@/lilypond/}.
Initialization files, for example @file{scm/@/lily@/.scm}, or
@end ignore
-@c Note: keep this node named so that `info lilypond-book' brings you here.
+@c Note: keep this node named so that @q{info lilypond-book} brings you here.
@node LilyPond-book
@chapter @command{lilypond-book}: Integrating text and music
@node Music fragment options
@section Music fragment options
-In the following, a ``LilyPond command'' refers to any command described
+In the following, a @qq{LilyPond command} refers to any command described
in the previous sections which is handled by @command{lilypond-book} to
produce a music snippet. For simplicity, LilyPond commands are only
shown in La@TeX{} syntax.
@item quote
Reduce line length of a music snippet by @math{2*0.4}@dmn{in} and put
-the output into a quotation block. The value `0.4@dmn{in}' can be
+the output into a quotation block. The value @q{0.4@dmn{in}} can be
controlled with the @code{exampleindent} option.
@item exampleindent
* Prepend GNU for dir, must be unique.
- * Do not list the `lilypond' node at toplevel, so that `info lilypond'
+ * Do not list the @q{lilypond} node at toplevel, so that @q{info lilypond}
goes to Top.
* List all commands in direntry.
@ifnottex
@node Top
@top GNU LilyPond --- The music typesetter
-@c HJJ: Info needs `@top', which is a synonym for `@unnumbered' in TeX.
+@c HJJ: Info needs @q{@top}, which is a synonym for @q{@unnumbered} in TeX.
This is the user manual for GNU LilyPond 2.10.x series.
@ifhtml
* Literature list:: Reference works about music notation.
* Scheme tutorial:: Programming inside LilyPond.
* Notation manual tables:: Tables and charts.
-* Example templates:: Ready-made templates.
+* Templates:: Ready-made templates.
* Cheat sheet:: Summary of LilyPond syntax.
* GNU Free Documentation License:: License of this document.
* LilyPond command index::
@ref{\NAME\,,,music-glossary}
@end macro
+@c to get decent quotes in `foo'
+@macro q{TEXT}
+@html
+‘\TEXT\’
+@end html
+@end macro
+
+@c to get decent quotes in ``foo''
+@macro qq{TEXT}
+@html
+“\TEXT\”
+@end html
+@end macro
+
@end ifhtml
@ref{\NAME\,,,music-glossary}
@end macro
+@c to get decent quotes in `foo'
+@macro q{TEXT}
+@xml
+‘\TEXT\’
+@end xml
+@end macro
+
+@c to get decent quotes in ``foo''
+@macro qq{TEXT}
+@xml
+“\TEXT\”
+@end xml
+@end macro
+
@end ifdocbook
@inforef{\NAME\}
@end macro
+@c to get decent quotes in `foo'
+@macro q{TEXT}
+`\TEXT\'
+@end macro
+
+@c to get decent quotes in ``foo''
+@macro qq{TEXT}
+``\TEXT\''
+@end macro
+
@end ifinfo
user manual, @internalsref{\NAME\}
@end macro
+@c to get decent quotes in `foo'
+@macro q{TEXT}
+`\TEXT\'
+@end macro
+
+@c to get decent quotes in ``foo''
+@macro qq{TEXT}
+``\TEXT\''
+@end macro
+
@end iftex
+
@ifnottex
@c **** not TEX ****
@end macro
+@macro moreinfo
+@subheading More information
+
+@end macro
+
@macro seealso
@noindent
@subsubheading See also
@kindex \WORD\
@end macro
-
+@c EOF
@author Adrian Mariano @c Italian glossary
@author Heikki Junes @c Finnish glossary
-@c Fixes by Jean-Pierre Coulon and `Dirk'
+@c Fixes by Jean-Pierre Coulon and @q{Dirk}
Copyright @copyright{} 1999--2006 by the authors
* alto::
* alto clef::
* ambit::
+* anacrusis::
* ancient minor scale::
* andante::
* appoggiatura::
* arpeggio::
+* articulation::
* ascending interval::
* augmented interval::
* autograph::
of pitches for a given voice in a part of music. It may also denote
the pitch range that a musical instrument is capable of playing.
+@node anacrusis
+@section anacrusis
+
+@c TODO: add more languages for anacrusis
+F: anacrouse
+
+An anacrusis (also known as pickup or upbeat) is an incomplete measure
+of music before a section of music.
+
@node ancient minor scale
@section ancient minor scale
>>
@end lilypond
+@node articulation
+@section articulation
+
+@c TODO: add languages for articulation.
+Articulation refers to notation which indicates how a note or notes should
+be played. Slurs, accents, staccato, and legato are all examples of
+articulartion.
+
+
@node ascending interval
@section ascending interval
FI: cresendo, voimistuen.
Increasing volume. Indicated by a rightwards opening horizontal wedge or the
-abbreviation ``cresc.''.
+abbreviation @qq{cresc.}.
@lilypond[fragment,ragged-right]
\key g \major \time 4/4
FI: da capo, alusta.
The term indicates repetition of the piece from the beginning to the end or
-to a certain place marked @emph{fine}. Mostly abbreviated as ``D.C.''.
+to a certain place marked @emph{fine}. Mostly abbreviated as @qq{D.C.}.
@node dal segno
@section dal segno
S: dal segno,
FI: dal segno, lähtien merkistä.
-Abbreviated ``d.s.''. Repetition, not from the beginning, but from
+Abbreviated @qq{d.s.}. Repetition, not from the beginning, but from
another place frequently near the beginning marked by a sign:
@lilypond[fragment,ragged-right]
FI: decresendo, hiljentyen.
Decreasing tone volume. Indicated by a leftwards opening horizontal wedge
-or the abbreviation ``decresc.''.
+or the abbreviation @qq{decresc.}.
@lilypond[fragment,ragged-right]
\relative c'' {
FI: johtosävel.
The seventh @aref{scale degree}, a @aref{semitone} below
-the tonic; so called because of its strong tendency to ``lead up'' (resolve
+the tonic; so called because of its strong tendency to @qq{lead up} (resolve
upwards) to the tonic scale degree.
@node ledger line
falls into three sections called @emph{exposition}, @emph{development} and
@emph{recapitulation}. In the exposition the composer introduces some musical
ideas, consisting of a number of themes; in the development section the
-composer `develops' this material, and in the recapitulation the composer
+composer @q{develops} this material, and in the recapitulation the composer
repeats the exposition, with certain modifications. The exposition contains a
number of themes that fall into two groups, often called first and second
subject. Other melodies occurring in each group are considered as
@section Input files
The main format of input for LilyPond are text files. By convention,
-these files end with ``@code{.ly}''.
+these files end with @q{@samp{.ly}}.
@menu
* File structure (introduction)::
The line @code{\include "file.ly"} is equivalent to pasting the contents
of file.ly into the current file at the place where you have the
\include. For example, for a large project you might write separate files
-for each instrument part and create a ``full score'' file which brings
+for each instrument part and create a @qq{full score} file which brings
together the individual instrument files.
The initialization of LilyPond is done in a number of files that are
finds.
Files placed in directory @file{PATH/TO/share/lilypond/VERSION/ly/} (where
-VERSION is in the form ``2.6.1'') are on the path and available to
+VERSION is in the form @qq{2.6.1}) are on the path and available to
@code{\include}. Files in the
current working directory are available to \include, but a file of the same
name in LilyPond's installation takes precedence. Files are
The default footer is empty, except for the first page, where the
@code{copyright} field from @code{\header} is inserted, and the last
page, where @code{tagline} from @code{\header} is added. The default
-tagline is ``Music engraving by LilyPond (@var{version})''.@footnote{Nicely
+tagline is @qq{Music engraving by LilyPond (@var{version})}.@footnote{Nicely
printed parts are good PR for us, so please leave the tagline if you
can.}
\context @{
\Voice
\remove "Dynamic_performer"
- \remove "Span_dynamic_performer"
@}
@}
@end example
X color names come several variants:
Any name that is spelled as a single word with capitalisation
-(e.g. ``LightSlateBlue'') can also be spelled as space separated
-words without capitalisation (e.g. ``light slate blue'').
+(e.g. @qq{LightSlateBlue}) can also be spelled as space separated
+words without capitalisation (e.g. @qq{light slate blue}).
-The word ``grey'' can always be spelled ``gray'' (e.g. ``DarkSlateGray'').
+The word @qq{grey} can always be spelled @qq{gray} (e.g. @qq{DarkSlateGray}).
-Some names can take a numerical suffix (e.g. ``LightSalmon4'').
+Some names can take a numerical suffix (e.g. @qq{LightSalmon4}).
@subsubheading Color Names without a numerical suffix:
and are used in some advanced situations. The @code{parser}
argument is used to access to the value of another LilyPond
variable. The @code{location} argument
-is used to set the ``origin'' of the music expression that is built
+is used to set the @qq{origin} of the music expression that is built
by the music function, so that in case of a syntax error LilyPond
can tell the user an appropriate place to look in the input file.
@noindent
is internally converted to a Scheme definition
@example
-(define traLaLa @var{Scheme value of ``@code{... }''})
+(define traLaLa @var{Scheme value of @q{@samp{... }}})
@end example
This means that input variables and Scheme variables may be freely
is executed before @code{traLaLa} is defined, leading to a syntax
error.
-The above example shows how to `export' music expressions from the
+The above example shows how to @q{export} music expressions from the
input to the Scheme interpreter. The opposite is also possible. By
wrapping a Scheme value in the function @code{ly:export}, a Scheme
value is interpreted as if it were entered in LilyPond syntax.
@internalsref{Music expressions}.
@item
-`type' or interface: Each music name has several `types' or
+@q{type} or interface: Each music name has several @q{types} or
interfaces, for example, a note is an @code{event}, but it is also a
@code{note-event}, a @code{rhythmic-event}, and a
@code{melodic-event}. All classes of music are listed in the
A compound music expression is a music object that contains other
music objects in its properties. A list of objects can be stored in
-the @code{elements} property of a music object, or a single `child'
+the @code{elements} property of a music object, or a single @q{child}
music object in the @code{element} object. For example,
@internalsref{SequentialMusic} has its children in @code{elements},
and @internalsref{GraceMusic} has its single argument in
@subsection Doubling a note with slurs (example)
Suppose we want to create a function which translates
-input like ``@code{a}'' into ``@code{a( a)}''. We begin
+input like @q{@samp{a}} into @q{@samp{a( a)}}. We begin
by examining the internal representation of the music
we want to end up with.
@end example
The bad news is that the @code{SlurEvent} expressions
-must be added ``inside'' the note (or more precisely,
+must be added @qq{inside} the note (or more precisely,
inside the @code{EventChord} expression).
Now we examine the input,
@example
doubleSlur = #(define-music-function (parser location note) (ly:music?)
"Return: @{ note ( note ) @}.
- `note' is supposed to be an EventChord."
+ @q{note} is supposed to be an EventChord."
(let ((note2 (ly:music-deep-copy note)))
(set! (ly:music-property note 'elements)
(cons (make-music 'SlurEvent 'span-direction -1)
@example
(define (add-marcato event-chord)
- "Add a marcato ArticulationEvent to the elements of `event-chord',
+ "Add a marcato ArticulationEvent to the elements of @q{event-chord},
which is supposed to be an EventChord expression."
(let ((result-event-chord (ly:music-deep-copy event-chord)))
(set! (ly:music-property result-event-chord 'elements)
(let ((result-event-chord (ly:music-deep-copy event-chord)))
@end example
-`@code{let}' is used to declare local variables. Here we use one local
-variable, named `@code{result-event-chord}', to which we give the value
-@code{(ly:music-deep-copy event-chord)}. `@code{ly:music-deep-copy}' is
+@samp{let} is used to declare local variables. Here we use one local
+variable, named @samp{result-event-chord}, to which we give the value
+@code{(ly:music-deep-copy event-chord)}. @samp{ly:music-deep-copy} is
a function specific to LilyPond, like all functions prefixed by
-`@code{ly:}'. It is use to make a copy of a music
+@samp{ly:}. It is use to make a copy of a music
expression. Here we copy `@code{event-chord} (the parameter of the
function). Recall that our purpose is to add a marcato to an
@code{EventChord} expression. It is better to not modify the
(ly:music-property result-event-chord 'elements))
@end example
-`@code{cons}' is used to add an element to a list without modifying the
+@samp{cons} is used to add an element to a list without modifying the
original list. This is what we
want: the same list as before, plus the new @code{ArticulationEvent}
expression. The order inside the elements property is not important here.
@example
addMarcato = #(define-music-function (parser location event-chord)
(ly:music?)
- "Add a marcato ArticulationEvent to the elements of `event-chord',
+ "Add a marcato ArticulationEvent to the elements of @q{event-chord},
which is supposed to be an EventChord expression."
(let ((result-event-chord (ly:music-deep-copy event-chord)))
(set! (ly:music-property result-event-chord 'elements)
@item argi-type?
a type predicate for the i@var{th} argument
@item layout
-the `layout' definition
+the @q{layout} definition
@item props
a list of alists, containing all active properties.
@end table
* Extending the templates::
* How LilyPond files work::
* Score is a single musical expression::
+* An orchestral part::
@end menu
Start off with the template that seems closest to what you want to end
up with. Let's say that you want to write something for soprano and
-cello. In this case, we would start with ``Notes and lyrics'' (for the
+cello. In this case, we would start with @qq{Notes and lyrics} (for the
soprano part).
@example
@}
@end example
-Now we want to add a cello part. Let's look at the ``Notes only'' example:
+Now we want to add a cello part. Let's look at the @qq{Notes only} example:
@example
\version "2.9.13"
text editor!
+
+
+
+
+@node An orchestral part
+@section An orchestral part
+
+In orchestral music, all notes are printed twice. Once in a part for
+the musicians, and once in a full score for the conductor. Identifiers can
+be used to avoid double work. The music is entered once, and stored in
+a variable. The contents of that variable is then used to generate
+both the part and the full score.
+
+It is convenient to define the notes in a special file. For example,
+suppose that the file @file{horn-music.ly} contains the following part
+of a horn/@/bassoon duo
+
+@example
+hornNotes = \relative c @{
+ \time 2/4
+ r4 f8 a cis4 f e d
+@}
+@end example
+
+@noindent
+Then, an individual part is made by putting the following in a file
+
+@example
+\include "horn-music.ly"
+\header @{
+ instrument = "Horn in F"
+@}
+
+@{
+ \transpose f c' \hornNotes
+@}
+@end example
+
+The line
+
+@example
+\include "horn-music.ly"
+@end example
+
+@noindent
+substitutes the contents of @file{horn-music.ly} at this position in
+the file, so @code{hornNotes} is defined afterwards. The command
+@code{\transpose f@tie{}c'} indicates that the argument, being
+@code{\hornNotes}, should be transposed by a fifth upwards. Sounding
+@samp{f} is denoted by notated @code{c'}, which corresponds with the
+tuning of a normal French Horn in@tie{}F. The transposition can be seen
+in the following output
+
+@lilypond[quote,ragged-right]
+\transpose f c' \relative c {
+ \time 2/4
+ r4 f8 a cis4 f e d
+}
+@end lilypond
+
+In ensemble pieces, one of the voices often does not play for many
+measures. This is denoted by a special rest, the multi-measure
+rest. It is entered with a capital @samp{R} followed by a duration
+(@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
+etc.). By multiplying the
+duration, longer rests can be constructed. For example, this rest
+takes 3@tie{}measures in 2/4 time
+
+@example
+R2*3
+@end example
+
+When printing the part, multi-rests
+must be condensed. This is done by setting a run-time variable
+
+@example
+\set Score.skipBars = ##t
+@end example
+
+@noindent
+This command sets the property @code{skipBars} in the
+@code{Score} context to true (@code{##t}). Prepending the rest and
+this option to the music above, leads to the following result
+
+@lilypond[quote,ragged-right]
+\transpose f c' \relative c {
+ \time 2/4
+ \set Score.skipBars = ##t
+ R2*3
+ r4 f8 a cis4 f e d
+}
+@end lilypond
+
+
+The score is made by combining all of the music together. Assuming
+that the other voice is in @code{bassoonNotes} in the file
+@file{bassoon-music.ly}, a score is made with
+
+@example
+\include "bassoon-music.ly"
+\include "horn-music.ly"
+
+<<
+ \new Staff \hornNotes
+ \new Staff \bassoonNotes
+>>
+@end example
+
+@noindent
+leading to
+
+@lilypond[quote,ragged-right]
+\relative c <<
+ \new Staff {
+ \time 2/4 R2*3
+ r4 f8 a cis4 f e d
+ }
+ \new Staff {
+ \clef bass
+ r4 d,8 f | gis4 c | b bes |
+ a8 e f4 | g d | gis f
+ }
+>>
+@end lilypond
+
+More in-depth information on preparing parts and scores can be found
+in the notation manual; see @ref{Orchestral music}.
+
+Setting run-time variables (@q{properties}) is discussed in
+@ref{Changing context properties on the fly}.
+
+
+
This chapter details the technicalities of running LilyPond.
Some of these commands are run from the command-line. By
-``command-line'', we mean the command
+@qq{command-line}, we mean the command
line in the operating system. Windows users
-might be more familiar with the terms ``DOS shell'' or
-``command shell''; OSX users might be more familiar with the
-terms ``terminal'' or ``console''. OSX users should also
+might be more familiar with the terms @qq{DOS shell} or
+@qq{command shell}; OSX users might be more familiar with the
+terms @qq{terminal} or @qq{console}. OSX users should also
consult @ref{Notes for the MacOS X app}.
Describing how to use
at the top of the @code{.ly} file.
@item -f,--format=@var{format}
-which formats should be written. Choices are @code{svg}, @code{ps},
-@code{pdf}, @code{png}, @code{tex}, @code{dvi}.
+which formats should be written. Choices for @code{format} are
+@code{svg}, @code{ps}, @code{pdf}, @code{png}, @code{tex}, @code{dvi}.
+
+Example: @code{lilypond -fpng filename.ly}
@item -b,--backend=@var{format}
-the output format to use for the back-end. Choices are
+the output format to use for the back-end. Choices for @code{format} are
@table @code
@item tex
for @TeX{} output, to be processed with La@TeX{}. If present, the file
@cindex Scheme dump
@end table
+Example: @code{lilypond -bsvg filename.ly}
+
@cindex output format, setting
@item -d,--define-default=@var{var}=@var{val}
The same is true of the other scripts in that directory, including
lilypond-book, convert-ly, abc2ly, etc.
-Alternatively, you may add this directory to your path. Modify (or create)
+Alternatively, you may create scripts which add the path
+automatically. Create a directory to store these scripts,
+
+@example
+mkdir -p ~/bin
+cd ~/bin
+@end example
+
+Create a file called @code{lilypond} which contains
+
+@example
+exec @var{path/to}/LilyPond.app/Contents/Resources/bin/lilypond "$@@"
+@end example
+
+Create similar files @code{lilypond-book}, @code{convert-ly}, and
+any other helper programs you use (@code{abc2ly}, @code{midi2ly},
+etc). Simply replace the @code{bin/lilypond} with
+@code{bin/convert-ly} (or other program name) in the above file.
+
+Make the file executable,
+
+@example
+chmod u+x lilypond
+@end example
+
+Now, add this directory to your path. Modify (or create)
a file called @code{.profile} in your home directory such that it contains
@example
-export PATH=$PATH:@var{path/to}/LilyPond.app/Contents/Resources/bin
+export PATH=$PATH:~/bin
@end example
@noindent
@uref{http://lilypond.org/web/devel/participating/bugs}
+Please construct submit @ref{Minimal examples} of bug reports. We do not
+have the resources to investigate reports which are not as small as possible.
+
@node Error messages
@section Error messages
@end ifnothtml
-@item JEdit
+@item LilyPondTool
-The @uref{http://@/www@/.jedit@/.org@/,jEdit} editor has a LilyPond plugin.
-This plugin includes a DVI viewer, integrated help and viewing via
-GhostScript. It can be installed by doing @key{Plugins > Plugin
-Manager}, and selecting @code{LilyTool} from the @key{Install} tab.
+Created as a plugin for the @uref{http://@/www@/.jedit@/.org@/,jEdit} text
+editor, LilyPondTool is the most feature-rich text-based tool for editing
+LilyPond scores. Its features include a Document Wizard with lyrics
+support to set up documents easier, and embedded PDF viewer with advanced
+point-and-click support. For screenshots, demos and installation
+instructions, visit @uref{http://lilypondtool@/.organum@/.hu}
@end table
width of staff lines. This makes stems almost twice as thick as their
normal size. To distinguish between variables defined in input files (like
@code{twentyFour} in the example above) and variables of internal
-objects, we will call the latter ``properties'' and the former
-``identifiers.'' So, the stem object has a @code{thickness} property,
+objects, we will call the latter @qq{properties} and the former
+@qq{identifiers.} So, the stem object has a @code{thickness} property,
while @code{twentyFour} is an identifier.
@cindex properties vs. identifiers
many pages a piece of music takes.
Globally speaking, this procedure happens in four steps: first,
-flexible distances (``springs'') are chosen, based on durations. All
-possible line breaking combinations are tried, and a ``badness'' score
+flexible distances (@qq{springs}) are chosen, based on durations. All
+possible line breaking combinations are tried, and a @qq{badness} score
is calculated for each. Then the height of each possible system is
estimated. Finally, a page breaking and line breaking combination is chosen
so that neither the horizontal nor the vertical spacing is too cramped
@subsection Horizontal spacing overview
The spacing engine translates differences in durations into stretchable
-distances (``springs'') of differring lengths. Longer durations get
+distances (@qq{springs}) of differring lengths. Longer durations get
more space, shorter durations get less. The shortest durations get a
fixed amount of space (which is controlled by
@code{shortest-duration-space} in the @internalsref{SpacingSpanner}
@refbugs
-Line breaks can only occur if there is a ``proper'' bar line. A note
+Line breaks can only occur if there is a @qq{proper} bar line. A note
which is hanging over a bar line is not proper, such as
@lilypond[quote,ragged-right,relative=2,fragment,verbatim]
of the parts does not throw off the @code{Page_turn_engraver}). When it finds
a sufficiently long section without notes, the @code{Page_turn_engraver} will
insert an @code{\allowPageTurn} at the final barline in that section, unless
-there is a ``special'' barline (such as a double bar), in which case the
-@code{\allowPageTurn} will be inserted at the final ``special'' barline in
+there is a @qq{special} barline (such as a double bar), in which case the
+@code{\allowPageTurn} will be inserted at the final @qq{special} barline in
the section.
@funindex minimumPageTurnLength
version that you are working on. See TRANSLATION for details.
@end ignore
-@node Example templates
-@appendix Example templates
+@node Templates
+@appendix Templates
This section of the manual contains templates with the LilyPond score
already set up for you. Just add notes, run LilyPond, and enjoy
@c make whatever changes I feel like.
@c FIXME: produces a warning ; key change merge.
-@c The `line-width' argument is for the \header.
+@c The @q{line-width} argument is for the \header.
@lilypond[quote,verbatim,ragged-right,line-width]
\version "2.9.13"
violin concerto as TchaikovskyPI, whereas perhaps you wish to print
"Petr Tchaikowski" on your music.
-@ The `line-width' is for \header.
+@ The @q{line-width} is for \header.
@li lypond[quote,verbatim,ragged-right,line-width]
\version "2.9.13"
\header {
version that you are working on. See TRANSLATION for details.
@end ignore
+@ignore
+Tutorial guidelines:
+- unless you have a really good reason, use either
+ @l ilypond[quote,ragged-right,verbatim]
+ or
+ @l ilypond[quote,ragged-right,verbatim,fragment,relative=2]
+ (without spaces)
+ Don't use any other relative=X commands (make it a non-fragment
+ example), and don't use fragment without relative=2.
+- use "aes" and "ees" instead of "as" and "aes". I know it's not
+ correct Dutch naming, but let's not confuse people with this until
+ we get to the Basic notation chapter.
+@end ignore
+
+
+
+@c old info that will probably be removed.
@c TODO:
@c * more details about running lilypond; error messages,
@c compiling/viewing (emacs?)
LilyPond input that was used to generate that image.
Try it on this image
-@lilypond[fragment,quote,ragged-right,relative=2]
-c-\markup { \bold \huge { Click here. } }
+@c no verbatim here
+@lilypond[quote,ragged-right]
+\relative c'' {
+ c-\markup { \bold \huge { Click here. } }
+}
@end lilypond
-@end ifhtml
-By cutting and pasting the full input into a test file, you have a
+By cutting and pasting everything in the @qq{ly snippet} section, you have a
starting template for experiments. If you like learning in this way,
-you will probably want to print out or bookmark
-@ifhtml
-the
-@end ifhtml
+you will probably want to print out or bookmark the
@ref{Cheat sheet}, which is a table listing of the most common
commands for quick reference.
+@end ifhtml
@menu
* First steps::
-* Second steps::
-* More about pitches::
-* Entering ties::
-* Automatic and manual beams::
-* Octave entry::
-* Music expressions explained::
-* More staves::
-* Adding articulation marks to notes::
-* Combining notes into chords::
-* Advanced rhythmic commands::
-* Commenting input files::
-* Printing lyrics::
-* A lead sheet::
-* Adding titles::
-* Single staff polyphony::
-* Piano staves::
-* Organizing larger pieces::
-* An orchestral part::
-* After the tutorial::
+* Single staff notation::
+* Multiple notes at once::
+* Songs::
+* Final touches::
@end menu
@node First steps
@section First steps
-The first example demonstrates how to enter the most elementary piece
-of music, a @rglos{scale}. A @rglos{note} can be entered by typing
-its name, from @samp{a} through @samp{g}. So, if you enter
+This section gives a basic introduction to working with LilyPond.
+
+@menu
+* Compiling a file::
+* Simple notation::
+* Working on text files::
+* How to read the tutorial::
+@end menu
+
+
+@node Compiling a file
+@subsection Compiling a file
+
+The first example demonstrates how to start working with LilyPond. To
+create sheet music, we write a text file that specifies the
+notation. For example, if we write
@example
@{
-c' d' e' f' g' a' b' c''
+ c' e' g' e'
@}
@end example
@noindent
the result looks like this
-@lilypond[quote]
+@c in this case we don't want verbatim
+@lilypond[quote,ragged-right]
{
-c' d' e' f' g' a' b' c''
+ c' e' g' e'
}
@end lilypond
-@emph{Warning:} Every piece of LilyPond input needs to have @{curly
-braces@} placed around the input. The braces should be also be
+@strong{Warning:} Every piece of LilyPond input needs to have @strong{@{ curly
+braces @}} placed around the input. The braces should also be
surrounded by a space unless they are at the beginning or end of a
-line to avoid ambiguities. These may be omitted in examples in this
+line to avoid ambiguities. These may be omitted in some examples in this
manual, but don't forget them in your own music!
@cindex Case sensitive
-In addition, LilyPond input is case sensitive. @code{ @{ c d e @} } is
-valid input; @code{ @{ C D E @} } will produce an error message.
-
+In addition, LilyPond input is @strong{case sensitive}. @code{ @{ c d e @} }
+is valid input; @code{ @{ C D E @} } will produce an error message.
+@sp 1
-@unnumberedsubsec Entering music and viewing output
+@subheading Entering music and viewing output
In this section we will explain what commands to run
and how to view or print the output.
-@unnumberedsubsubsec MacOS X
+@subsubheading MacOS X
If you double click LilyPond.app, it will open with an example
file. Save it, for example, to @file{test.ly} on your Desktop, and
then process it with the menu command @samp{Compile > Typeset File}.
The resulting PDF file will be displayed on your screen.
-Be warned that the first time you ever run lilypond will take a minute
-or two, because all of the system fonts have to be analyzed first.
+Be warned that the first time you ever run LilyPond, it will take a minute
+or two because all of the system fonts have to be analyzed first.
For future use of LilyPond, you should begin by selecting "New"
-or "Open".
+or "Open". You must save your file before typesetting it. If any errors
+occur in processing, please see the log window.
-@unnumberedsubsubsec Windows
+@subsubheading Windows
On Windows, start up a text-editor@footnote{Any simple or
programmer-oriented editor with UTF-8 support will do, for example
codes that will confuse LilyPond.} and enter
@verbatim
-{ c' e' g' c'' }
+{
+ c' e' g' e'
+}
@end verbatim
Save it on the desktop as @file{test.ly} and make sure that it is not
called @file{test.ly.TXT}. Double clicking @file{test.ly} will process
-the file and show the resulting PDF file.
+the file and show the resulting PDF file. To edit an existing
+@file{.ly} file, right-click on it and select @qq{Edit source}.
+If you double-click in the LilyPond icon on the Desktop, it will open
+a simple text editor with an example file. Save it, for example, to
+@file{test.ly} on your Desktop, and then double-click on the file to
+process it. After some seconds, you will get a file @file{test.pdf}
+on your desktop. Double-click on this PDF file to view the typeset
+score. An alternative method to process the @file{test.ly} file
+is to drag and drop it onto the LilyPond icon using your mouse pointer.
-@unnumberedsubsubsec Unix
+Double-clicking the file does not only result in a PDF file, but also
+produces a @file{.log} file that contains some information on what LilyPond
+has done to the file. If any errors occur, please examine this file.
+
+
+@subsubheading Unix
Begin by opening a terminal window and starting a text editor. For
example, you could open an xterm and execute
@code{joe}@footnote{There are macro files for VIM addicts, and there
is a @code{LilyPond-mode} for Emacs addicts. If they have not been
-installed already, refer to the file @file{INSTALL.txt}.}. In your
+installed already, refer to the file @file{INSTALL.txt}. The
+easiest editing environment is @file{LilyPondTool}. See
+@ref{Editor support} for more information.}. In your
text editor, enter the following input and save the file as
@file{test.ly}
@verbatim
-{ c' e' g' c'' }
+{
+ c' e' g' e'
+}
@end verbatim
@noindent
@noindent
The result is the file @file{test.pdf} which you can print or view
with the standard facilities of your operating system.@footnote{If
-your system does not have any tools installed, you can try
+your system does not have any such tools installed, you can try
@uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, a freely
available package for viewing and printing PDF and PostScript files.}
-@node Second steps
-@section Second steps
+@node Simple notation
+@subsection Simple notation
-@emph{Remember:} Every piece of LilyPond input needs to have @{curly
-braces@} placed around the input. The braces should be surrounded by
-a space unless they are at the beginning or end of a line to avoid
-ambiguities. For the rest of this manual, most examples will omit
-these braces, but don't forget them in your own music!
+LilyPond will add some notation elements automatically. In the next
+example, we have only specified four pitches, but LilyPond has
+added a clef, time signature, and rhythms.
-@c will be removed once the tutorial either explains \relative or
-@c examples are fixed so they don't use it. -gp
-In addition, many examples use @code{relative} mode. This is explained
-in @ref{Octave entry}; for now simply be aware that some examples
-should be placed inside @code{\relative @{ @emph{...music...} @}}.
-Many example have also been compressed horizontally to save
-space, using @code{\paper @{ ragged-right = ##t @}}.
+@lilypond[quote,ragged-right,verbatim]
+{
+ c' e' g' e'
+}
+@end lilypond
-@cindex Case sensitive
-Finally, LilyPond input is case sensitive. @code{ @{ c d e @} } is
-valid input; @code{ @{ C D E @} } will produce an error message.
+@noindent
+This behavior may be altered, but in most cases these automatic values
+are useful.
-@c End of latest re-write. Since I have no life, I may do more
-@c work on this, but I'd really like to have a Doc Helper take
-@c over this task. -gp
+@subheading Pitches
-The @rglos{duration} of a note is specified by a number after the note
-name. @samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note},
-@samp{4} for a @rglos{quarter note} and so on
+The easiest way to enter notes is by using @code{\relative} mode. In
+this mode, the @rglos{interval} between the previous note and the
+current note is assumed to be within a @rglos{fourth}. We begin by
+entering the most elementary piece of music, a @rglos{scale}.
-@example
-a1 a2 a4 a16 a32
-@end example
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+ c d e f
+ g a b c
+}
+@end lilypond
+
+The initial note is @rglos{middle C}. Each successive note
+is within a fourth of the previous note -- in other words, the first
+@samp{c} is the closest C to middle C. This is followed by the closest
+D to the previous note. We can create melodies which have larger intervals:
-@lilypond[fragment,quote,notime,relative=2]
-\set Staff.autoBeaming = ##f
-{ a1 a2 a4 a16 a32 s16_" " }
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+ d f a g
+ c b f d
+}
@end lilypond
-If you do not specify a duration, the duration last entered is used
-for the next notes. The duration of the first note in input defaults
-to a quarter
+@noindent
+As you may notice, this example does not start on middle C. The first
+note -- the @samp{d} -- is the closest D to middle C.
-@example
-a a8 a a2 a
-@end example
+To add intervals that are larger than a fourth, we can raise the octave
+by adding a single quote @code{'} (or apostrophe) to the note name. We can
+lower the octave by adding a comma @code{,} to the note name.
-@lilypond[fragment,quote,notime,relative=2]
-{ a a8 a a2 a s16_" " }
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ a a, c' f,
+ g g'' a,, f'
+}
@end lilypond
+@noindent
+To change a note by two (or more!) octaves, we use multiple @code{''} or
+@code{,,} -- but be careful that you use two single quotes @code{''} and
+not one double quote @code{"}@tie{}! The initial value in
+@code{\relative c'} may also be modified like this.
-A @rglos{rest} is entered just like a note, but with the name @samp{r}
-@example
-r2 r4 r8 r16
-@end example
+@subheading Durations (rhythms)
+
+The @rglos{duration} of a note is specified by a number after the note
+name. @samp{1} for a @rglos{whole note}, @samp{2} for a @rglos{half note},
+@samp{4} for a @rglos{quarter note} and so on. Beams are added
+automatically.
-@lilypond[fragment,quote,notime]
-r2 r4 r8 r16 s16_" "
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ a1
+ a2 a4 a8 a
+ a16 a a a a32 a a a a64 a a a a a a a a2
+}
@end lilypond
-Add a dot @samp{.} after the duration to get a @rglos{dotted note}
+@noindent
+If you do not specify a duration, the previous duration is used
+for the next note. The duration of the first note defaults to a quarter.
-@example
-a2. a4 a8. a16
-@end example
+To create @rglos{dotted notes}, add a dot @samp{.} to the duration number.
-@lilypond[fragment,quote,notime,relative=1]
-{ a2. a4 a8. a16 s16_" " }
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ a a a4. a8
+ a8. a16 a a8. a8 a4.
+}
@end lilypond
-The (or @rglos{time signature}) can be set with the @code{\time}
-command
-@example
-\time 3/4
-\time 6/8
-\time 4/4
-@end example
+@subheading Rests
+
+A @rglos{rest} is entered just like a note with the name @samp{r}:
-@c A clef here may lead to confusion, remove it.
-@lilypond[fragment,quote]
-\override Staff.Clef #'transparent = ##t
-\time 3/4
-s4_" "
-\time 6/8
-s4_" "
-\time 4/4
-s16_" "
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ a r r2
+ r8 a r4 r4. r8
+}
@end lilypond
-The @rglos{clef} can be set using the @code{\clef} command
-@example
-\clef treble
-\clef bass
-\clef alto
-\clef tenor
-@end example
+@subheading Time signature
+
+The @rglos{time signature}) can be set with the @code{\time} command:
-@lilypond[fragment,quote,notime]
-\clef treble
-s4_" "
-\clef bass
-s4_" "
-\clef alto
-s4_" "
-\clef tenor
-s16_" "
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ \time 3/4
+ a4 a a
+ \time 6/8
+ a4. a
+ \time 4/4
+ a4 a a a
+}
@end lilypond
-Remember to enclose the notes and commands in curly braces
-@code{@{@tie{}@dots{}@tie{}@}} to convert it to printable output.
-@lilypond[fragment,quote,noindent,verbatim]
-\time 3/4
-\clef bass
-c2 e4 g2.
-f4 e d c2 r4
+@subheading Clef
+
+The @rglos{clef} can be set using the @code{\clef} command:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c' {
+ \clef treble
+ c1
+ \clef alto
+ c1
+ \clef tenor
+ c1
+ \clef bass
+ c1
+}
@end lilypond
-For more information on
+@subheading All together
+
+Here is a small example showing all these elements together:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c, {
+ \time 3/4
+ \clef bass
+ c2 e8 c' g'2.
+ f4 e d c4 c, r4
+}
+@end lilypond
+
+@moreinfo
@quotation
@table @asis
@item Entering pitches and durations
-see
-@ref{Pitches}, and @ref{Durations}.
-@item Clefs
-see @ref{Clef}.
+see @ref{Pitches} and @ref{Durations}.
@item Rests
see @ref{Rests}.
@item Time signatures and other timing commands
see @ref{Time signature}.
+@item Clefs
+see @ref{Clef}.
+@end table
+@end quotation
+
+
+@node Working on text files
+@subsection Working on text files
+
+LilyPond input files are treated like files in most programming languages:
+they are case sensitive, white-space insensitive, expressions are
+formed with curly braces @{ @}, and comments are denoted with @code{%} or
+@code{%@{ .. %@}}.
+
+If the previous sentence sounds like nonsense, don't worry! We'll explain
+what all these terms mean:
+
+@itemize
+
+@cindex Case sensitive
+@item @strong{Case sensitive}:
+it matters whether you enter a letter
+in lower case (i.e. @code{a, b, s, t}) or upper case (i.e.
+@code{A, B, S, T}). Notes are lower case: @code{ @{ c d e @} }
+is valid input; @code{ @{ C D E @} } will produce an error message.
+
+@item @strong{Whitespace insensitive}:
+it does not matter how many
+spaces (or new lines) you add. @code{ @{ c d e @}} means the same thing
+as @code{ @{ c @ @ @ @ @ d e @} } and
+@example
+ @{
+c d
+ e @}
+@end example
+
+@noindent
+Of course, the previous example is hard to read. A good rule of thumb
+is to indent code blocks with either a tab or two spaces:
+@example
+@{
+ c d e
+@}
+@end example
+
+@item @strong{Expressions:}
+Every piece of LilyPond input needs to have
+@strong{@{ curly braces @}} placed around the input. These braces tell
+LilyPond that the input is a single music expression, just like
+parenthesis @samp{()} in mathematics. The braces should
+be surrounded by a space unless they are at the beginning or end of a
+line to avoid ambiguities.
+
+A function (such as @code{\relative @{ @}} ) also counts as a single
+music expression.
+
+@cindex comments
+@cindex line comment
+@cindex block comment
+@item @strong{Comments}:
+A comment is a remark for the human reader of the music input; it is
+ignored while parsing, so it has no effect on the printed output.
+There are two types of comments. The percent symbol @samp{%}
+introduces a line comment; anything after @samp{%} on that line is
+ignored. A block comment marks a whole section of music
+input as a comment. Anything that is enclosed in @code{%@{} and @code{%@}} is
+ignored. The following fragment shows possible uses for comments
+
+@example
+% notes for twinkle twinkle follow
+ c4 c g' g a a g2
+
+%@{
+ This line, and the notes below
+ are ignored, since they are in a
+ block comment.
+
+ g g f f e e d d c2
+%@}
+@end example
+
+@end itemize
+
+There are more tips for constructing input files in
+@ref{Suggestions for writing LilyPond files}.
+
+
+@node How to read the tutorial
+@subsection How to read the tutorial
+
+As we saw in @ref{Working on text files}, LilyPond input must be
+surrounded by @{ @} marks or a @code{\relative c'' @{ ... @}}. For the
+rest of this manual, most examples will omit this.
+
+If you are reading the HTML documentation and wish to see the exact
+exact LilyPond code that was used to create the example, simply click
+on the picture. If you are not reading the HTML version, you could
+copy and paste the displayed input, but you @strong{must} add the
+@code{\relative c'' @{ @}} like this:
+
+@example
+\relative c'' @{
+ ... example goes here...
+@}
+@end example
+
+Why omit the braces? Most examples
+in this manual can be inserted into the middle of a longer piece of
+music. For these examples, it does not make sense to add
+@code{\relative c'' @{ @}} -- you should not place a @code{\relative}
+inside another @code{\relative}, so you would not be able to copy
+a small documentation example and paste it inside a longer piece
+of your own.
+
+
+@node Single staff notation
+@section Single staff notation
+
+This section introduces common notation that is used for one voice
+on one staff.
+
+@menu
+* Relative note names::
+* Accidentals and key signatures::
+* Ties and slurs::
+* Articulation and dynamics::
+* Automatic and manual beams::
+* Advanced rhythmic commands::
+@end menu
+
+
+@node Relative note names
+@subsection Relative note names
+
+As we saw in @ref{Simple notation}, LilyPond calculates the pitch of
+each note relative to the previous one@footnote{There is another mode of
+entering pitches, @ref{Absolute note names}, but in practice relative
+mode is much easier and safer to use.}. If no extra octave marks
+(@code{'} and @code{,}) are added, it assumes that each pitch is within
+a fourth of the previous note.
+
+LilyPond examines pitches based on the note names -- in other words,
+an augmented fourth is @emph{not} the same as a diminished fifth. If we
+begin at a C, then an F-sharp will be placed a higher than the C, while
+a G-flat will be placed lower than the C.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c2 fis
+c2 ges
+@end lilypond
+
+@moreinfo
+@quotation
+@table @asis
+@item Relative octaves
+see @ref{Relative octaves}.
+@item Octave check
+see @ref{Octave check}.
@end table
@end quotation
-@node More about pitches
-@section More about pitches
+
+@node Accidentals and key signatures
+@subsection Accidentals and key signatures
+
+@subheading Accidentals
A @rglos{sharp} pitch is made by adding @samp{is} to
-the name, a @rglos{flat} pitch by adding @samp{es}. As
+the name, and a @rglos{flat} pitch by adding @samp{es}. As
you might expect, a @rglos{double sharp} or @rglos{double flat} is
made by adding @samp{isis} or @samp{eses}@footnote{This syntax
derived from note naming conventions in Nordic and Germanic languages,
-like German and Dutch.}
-
-@example
-cis1 ees fisis aeses
-@end example
+like German and Dutch. To use other names for accidentals, see
+@ref{Note names in other languages}.}
-@lilypond[fragment,quote,notime]
-\set Score.timing = ##f
-\transpose c c' { cis1 ees fisis aeses s16_" " }
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+cis1 ees fisis, aeses
@end lilypond
@cindex key signature, setting
-The key signature is set with the command @code{\key}, followed by
-a pitch and @code{\major} or @code{\minor}
+@subheading Key signatures
-@example
-\key d \major
-g1
-\key c \minor
-g
-@end example
+The key signature is set with the command @code{\key} followed by
+a pitch and @code{\major} or @code{\minor}.
-@lilypond[fragment,quote,notime,fragment]
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
\key d \major
-g'1
+a1
\key c \minor
-g'
+a
@end lilypond
-@noindent
-Key signatures together with the pitches (including alterations) are
-used to determine when to print accidentals. This is a
+@sp 1
+
+@subheading Warning: key signatures and pitches
+
+To determine whether to print an accidental, LilyPond examines the
+pitches and the key signature. The key signature only effects
+the @emph{printed} accidentals, not the actual pitches! This is a
feature that often causes confusion to newcomers, so let us explain it
in more detail.
-
LilyPond makes a sharp distinction between musical content and
layout. The alteration (flat, natural or sharp) of a note is part of
the pitch, and is therefore musical content. Whether an accidental (a
-flat, natural or sharp @emph{sign}) is printed in front of the
+@emph{printed} flat, natural or sharp sign) is printed in front of the
corresponding note is a question of layout. Layout is something that
follows rules, so accidentals are printed automatically according to
those rules. The pitches in your music are works of art, so they will
In this example
-@lilypond[quote,notime,fragment]
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
\key d \major
-d' cis' fis'
+d cis fis
@end lilypond
@noindent
-no note has an explicit accidental, but you still must enter
-
-@example
-\key d \major
-d cis fis
-@end example
+No note has a printed accidental, but you must still add the @samp{is} to
+@code{cis} and @code{fis}.
-@noindent
-The code @samp{d} does not mean `print a black dot just below the
-staff.' Rather, it means: `a note with pitch D-natural.' In the key
-of A-flat major, it does get an accidental
+The code @samp{e} does not mean @qq{print a black dot just below the
+first line of the staff.} Rather, it means: @qq{there is a note with
+pitch E-natural.} In the key of A-flat major, it @emph{does} get an
+accidental:
-@lilypond[quote,notime,fragment,relative=1,verbatim]
-\key as \major
-d
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\key aes \major
+e
@end lilypond
Adding all alterations explicitly might require a little more effort
when typing, but the advantage is that transposing is easier, and
accidentals can be printed according to different conventions. See
-@ref{Automatic accidentals}, for some examples how accidentals can be printed
+@ref{Automatic accidentals} for some examples how accidentals can be printed
according to different rules.
-
-For more information on
-
+@moreinfo
@quotation
@table @asis
@item Accidentals
-see @ref{Automatic accidentals}.
-
+see @ref{Accidentals} and @ref{Automatic accidentals}.
@item Key signature
see @ref{Key signature}.
@end table
@end quotation
-@node Entering ties
-@section Entering ties
-@cindex tie
+@node Ties and slurs
+@subsection Ties and slurs
+
+@cindex ties
+@subheading Ties
A @rglos{tie} is created by appending a tilde @samp{~} to the first
note being tied
-@lilypond[quote,notime,fragment,verbatim,relative=3]
-g4~ g a2~ a4
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+g4~ g c2~
+c4 ~ c8 a8 ~ a2
@end lilypond
-For more information on Ties see @ref{Ties}.
-
+@cindex slurs
+@subheading Slurs
+A @rglos{slur} is a curve drawn across many notes. The starting note
+and ending note are marked with @samp{(} and @samp{)} respectively.
-@node Automatic and manual beams
-@section Automatic and manual beams
-
-@cindex beams, by hand
-All @rglos{beam}s are drawn automatically
-
-@lilypond[quote,fragment,relative=2,verbatim]
-a8 ais d es r d
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+d4( c16) cis( d e c cis d) e( d4)
@end lilypond
-@noindent
-If you do not like where beams are put, they can be entered by
-hand. Mark the first note to be beamed with @samp{[} and the last one
-with @samp{]}.
+@cindex slurs, phrasing
+@cindex phrasing slurs
+@subheading Phrasing slurs
-@lilypond[quote,fragment,relative=2,verbatim]
-a8[ ais] d[ es r d]
+@cindex phrasing slurs
+Slurs to indicate longer phrasing can be entered with @code{\(} and
+@code{\)}. You can have both legato slurs and phrasing slurs at the
+same time, but you cannot have simultaneous slurs or simultaneous
+phrasing slurs.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+a8(\( ais b c) cis2 b'2 a4 cis,\)
@end lilypond
-For more information on beams, see @ref{Manual beams}.
+@sp 1
+@cindex slurs versus ties
+@subheading Warnings: slurs vs. ties
-Here are key signatures, accidentals and ties in action
+A slur looks like a @rglos{tie}, but it has a different meaning. A
+tie simply makes the first note longer, and can only be used on
+pairs of notes with the same pitch. Slurs indicate the articulations
+of notes, and can be used on larger groups of notes. Slurs and ties
+can be nested.
-@lilypond[fragment,quote,noindent,line-width=50\staff-space,verbatim]
-\relative c'' {
- \time 4/4
- \key g \minor
- \clef treble
- r4 r8 a8 gis4 b
- a8 d4.~ d e,8
- fis4 fis8 fis8 eis4 a8 gis~
- gis2 r2
-}
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c2~( c8 fis fis4 ~ fis2 g2)
@end lilypond
-@cindex accidentals
-
-
-@noindent
-There are some interesting points to note in this example. Bar lines
-and beams are drawn automatically. Line breaks are calculated
-automatically; it does not matter where the line breaks are in the
-source file. Finally, the order in which time, key, and clef changes
-are entered is not relevant: in the printout, these are ordered
-according to standard notation conventions.
+@moreinfo
+@quotation
+@table @asis
+@item Ties
+see @ref{Ties}.
+@item Slurs
+see @ref{Slurs}.
+@item Phrasing slurs
+see @ref{Phrasing slurs}.
+@end table
+@end quotation
+@node Articulation and dynamics
+@subsection Articulation and dynamics
-@node Octave entry
-@section Octave entry
+@cindex articulation
+@cindex accents
+@cindex staccato
+@subheading Articulations
+Common @rglos{articulations} can be added to a note using a dash @samp{-}
+and a single character:
-@c Tim wants to move this quotes example just before the: quotes-do not-work
-@c score, but we'd need to remove quotes from the other two (key and
-@c tie) examples...
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c-. c-- c-> c-^ c-+ c-_
+@end lilypond
-@c better to have this just before the `octaves are bad' snipped
-@c but we'd need to remove the ', from \key and tie
-To raise a note by an octave, add a high quote @code{'} (apostrophe) to
-the note name, to lower a note one octave, add a `low quote' @code{,}
-(comma). Middle C is @code{c'}
+@cindex fingering
+@subheading Fingerings
+Similarly, fingering indications can be added to a note using a dash
+(@samp{-}) and the digit to be printed:
-@lilypond[quote,notime,fragment,verbatim]
-c'4 c'' c''' \clef bass c c,
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c-3 e-5 b-2 a-1
@end lilypond
-An example of the use of quotes is in the following Mozart fragment
+Articulations and fingerings are usually placed automatically, but you
+can specify a direction using @samp{^} (up) or @samp{_} (down). You can
+also use multiple articulations on the same note. However, in most cases
+it is best to let LilyPond determine the articulation directions.
-@lilypond[quote,ragged-right,fragment,verbatim]
-\key a \major
-\time 6/8
-cis''8. d''16 cis''8 e''4 e''8
-b'8. cis''16 b'8 d''4 d''8
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c_-^1 d^. f^4_2-> e^-_+
@end lilypond
-@noindent
-This example shows that music in a high register needs lots of quotes.
-This makes the input less readable, and it is a source of errors. The
-solution is to use `relative octave' mode. This is the
-most convenient way to copy existing music.
-
-In relative mode, a note without octavation quotes (i.e., the @code{'}
-or @code{,} after a note) is chosen so that it is closest to the
-previous one. For example, @samp{c f} goes up while @samp{c g} goes
-down.
+@subheading Dynamics
+Dynamic signs are made by adding the markings (with a backslash) to
+the note
-To use relative mode, add @code{\relative} before the piece of
-music. The first note is taken relative to the middle C
-@c no , for this sentence
-(i.e., @code{c'})
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c\ff c\mf c\p c\pp
+@end lilypond
+@cindex dynamics
+@cindex decrescendo
+@cindex crescendo
+Crescendi and decrescendi are started with the commands @code{\<} and
+@code{\>}. An ending dynamic, for example @code{\f}, will finish the
+(de)crescendo, or the command @code{\!} can be used
-@lilypond[quote,notime,fragment,verbatim]
-\relative {
- c' f c g c
-}
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c2\< c2\ff\> c2 c2\!
@end lilypond
-
-Since most music has small intervals, pieces can be written almost
-without octavation quotes in relative mode. The previous example is
-entered as
-
-@lilypond[quote,ragged-right,verbatim]
-\relative {
- \key a \major
- \time 6/8
- cis'8. d16 cis8 e4 e8
- b8. cis16 b8 d4 d8
-}
+@moreinfo
+@quotation
+@table @asis
+@item Articulations
+see @ref{Articulations}.
+@item Fingering
+see @ref{Fingering instructions}.
+@item Dynamics
+see @ref{Dynamics}.
+@end table
+@end quotation
+
+
+@node Automatic and manual beams
+@subsection Automatic and manual beams
+
+@cindex beams, by hand
+All @rglos{beam}s are drawn automatically:
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+a8 ais d ees r d c16 b a8
@end lilypond
-@c needed better, maybe even redundant explanation
-@c added another example below.
-@c grappig: Pa vond het heel logies, en slim toen-i eenmaal begreep.
-@c in eerste instantie drong het `relative' niet door zonder extra uitleg.
-Larger intervals are made by adding octavation quotes.
+@noindent
+If you do not like the automatic beams, they may be overridden
+manually. Mark the first note to be beamed with @samp{[} and the last one
+with @samp{]}.
-@lilypond[quote,notime,verbatim,fragment]
-\relative c {
- c'' f, f c' c g' c,
-}
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+a8[ ais] d[ ees r d] a b
@end lilypond
-In summary, quotes or commas no longer determine the absolute height
-of a note in @code{\relative} mode. Rather, the height of a note is
-relative to the previous one, and changing the octave of a single note
-shifts all following notes an octave up or down.
+@moreinfo
+@quotation
+@table @asis
+@item Automatic beams
+see @ref{Automatic beams}.
+@item Manual beams
+see @ref{Manual beams}.
+@end table
+@end quotation
+
+
+@node Advanced rhythmic commands
+@subsection Advanced rhythmic commands
-For more information on relative octaves see @ref{Relative octaves},
-and @ref{Octave check}.
+@cindex pickup
+@cindex anacruse
+@cindex partial measure
+@subheading Partial measure
+A pickup (or @rglos{anacrusis}) is entered with the keyword
+@code{\partial}. It is followed by a duration: @code{\partial 4} is
+a quarter note pickup and @code{\partial 8} an eighth note.
-@node Music expressions explained
-@section Music expressions explained
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\partial 8
+f8 c2 d
+@end lilypond
+
+@cindex tuplets
+@cindex triplets
+@subheading Tuplets
+
+Tuplets are made with the @code{\times} keyword. It takes two
+arguments: a fraction and a piece of music. The duration of the piece
+of music is multiplied by the fraction. Triplets make notes occupy
+2/3 of their notated duration, so a triplet has 2/3 as its fraction
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\times 2/3 { f8 g a }
+\times 2/3 { c r c }
+\times 2/3 { f,8 g16 a g a }
+\times 2/3 { d4 a8 }
+@end lilypond
+
+@cindex grace notes
+@cindex acciaccatura
+@cindex appoggiatura
+@subheading Grace notes
+
+Grace notes are created with the @code{\grace} command, although they
+can also be created by prefixing a music expression with the
+keyword @code{\appoggiatura} or @code{\acciaccatura}
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+c2 \grace { a32 b} c2
+c2 \appoggiatura b16 c2
+c2 \acciaccatura b16 c2
+@end lilypond
+
+@moreinfo
+@quotation
+@table @asis
+@item Grace notes
+see @ref{Grace notes},
+@item Tuplets
+see @ref{Tuplets},
+@item Pickups
+see @ref{Partial measures}.
+@end table
+@end quotation
-In input files, music is represent by so-called @emph{music
-expression}s. We have already seen some in the previous examples;
-a single note is a music expression
-@lilypond[fragment,quote,verbatim,relative=3]
+@node Multiple notes at once
+@section Multiple notes at once
+
+This section introduces having more than one note at the same time:
+multiple instruments, multiple staves for a single instrument (i.e. piano),
+and chords.
+
+Polyphony in music refers to having more than one voice occurring in
+a piece of music. Polyphony in LilyPond refers to having more than
+one voice on the same staff.
+
+@menu
+* Music expressions explained::
+* Multiple staves::
+* Piano staves::
+* Single staff polyphony::
+* Combining notes into chords::
+@end menu
+
+
+@node Music expressions explained
+@subsection Music expressions explained
+
+In LilyPond input files, music is represented by @emph{music
+expressions}. A single note is a music expression, although it is not
+valid input all on its own.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
a4
@end lilypond
-Enclosing a group of notes in braces creates a new music
-expression
+Enclosing a group of notes in braces creates a new music expression:
-@lilypond[fragment,quote,verbatim,relative=3]
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
{ a4 g4 }
@end lilypond
-Putting a bunch of music expressions (e.g., notes) in braces, means that
-they should be played in sequence. The result again is a music
-expression, which can be grouped with other expressions sequentially.
-Here, the expression from the previous example is combined with two
-notes
+Putting a group of music expressions (e.g. notes) in braces means that
+they are in sequence (i.e. each one follows the previous one). The result
+is another music expression:
-@lilypond[fragment,quote,verbatim,relative=3]
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
{ { a4 g } f g }
@end lilypond
-This technique is useful for non-monophonic music. To enter music
-with more voices or more staves, we also combine expressions in
-parallel. Two voices that should play at the same time, are entered
-as a simultaneous combination of two sequences. A `simultaneous'
-music expression is formed by enclosing expressions in @code{<<} and
-@code{>>}. In the following example, three sequences (all containing
-two separate notes) are combined simultaneously
+@subheading Simultaneous music expressions: multiple staves
-@lilypond[fragment,quote,verbatim,relative=3]
-<<
- { a4 g }
- { f e }
- { d b }
->>
+This technique is useful for polyphonic music. To enter music
+with more voices or more staves, we combine expressions in
+parallel. To indicate that two voices should play at the same time,
+simply enter a simultaneous combination of music expressions. A
+@q{simultaneous} music expression is formed by enclosing expressions inside
+@code{<<} and @code{>>}. In the following example, three sequences (all
+containing two separate notes) are combined simultaneously:
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ <<
+ { a4 g }
+ { f e }
+ { d b }
+ >>
+}
+@end lilypond
+
+Note that we have indented each level of the input with a different
+amount of space. LilyPond does not care how much (or little) space there
+is at the beginning of a line, but indenting LilyPond code like this makes
+it much easier for humans to read.
+
+@strong{Warning}: each note is relative to the
+previous note in the input, not relative to the @code{c''} in the
+initial @code{\relative} command.
+
+
+@subheading Simultaneous music expressions: single staff
+
+To determine the number of staves in a piece, LilyPond looks at the first
+expression. If it is a single note, there is one staff; if there is a
+simultaneous expression, there is more than one staff.
+
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ c2 <<c e>>
+ << { e f } { c <<b d>> } >>
+}
@end lilypond
+@cindex expression
+@cindex music expression
+@subheading Analogy: mathematical expressions
+
This mechanism is similar to mathematical
formulas: a big formula is created by composing small formulas. Such
-formulas are called expressions, and their definition is recursive, so
+formulas are called expressions, and their definition is recursive so
you can make arbitrarily complex and large expressions. For example,
@example
((1 + 2) * 3) / (4 * 5)
@end example
-@cindex expression
-@cindex music expression
This is a sequence of expressions, where each expression is contained
in the next (larger) one. The simplest expressions are numbers, and larger
ones are made by combining expressions with operators (like @samp{+},
music expressions can be nested arbitrarily deep, which is necessary
for complex music like polyphonic scores.
-Note that this example only has one staff, whereas
-the previous example had three separate staves. That is because this
-example begins with a single note. To determine the number of staves,
-LilyPond looks at the first element. If it is a single note, there is one
-staff; if there is a simultaneous expression, there is more than one staff.
-
-@lilypond[fragment,quote,verbatim,relative=2]
-{
- c <<c e>>
- << { e f } { c <<b d>> } >>
-}
-@end lilypond
-
-Music files with deep nesting can be confusing to enter and
-maintain. One convention that helps against this confusion is
-indenting. When entering a file with deep nesting of braces and
-angles, it is customary to use an indent that indicates the nesting
-level. Formatting music like this eases reading and helps you insert
-the right number of closing braces at the end of an expression. For
-example,
-
-@example
-<<
- @{
- @dots{}
- @}
- @{
- @dots{}
- @}
->>
-@end example
-Some editors have special support for entering LilyPond, and can help
-indenting source files. See @ref{Editor support} for more information.
+@node Multiple staves
+@subsection Multiple staves
-@node More staves
-@section More staves
+As we saw in @ref{Music expressions explained}, LilyPond input files
+are constructed out of music expressions. If the score begins with
+simultaneous music expressions, LilyPond creates multiples staves. However,
+it is easier to see what happens if we create each staff explicitly.
To print more than one staff, each piece of music that makes up a
staff is marked by adding @code{\new Staff} before it. These
@code{Staff} elements are then combined in parallel with @code{<<} and
-@code{>>}, as demonstrated here
+@code{>>}:
-@lilypond[quote,fragment,verbatim]
-<<
- \new Staff { \clef treble c'' }
- \new Staff { \clef bass c }
->>
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ <<
+ \new Staff { \clef treble c }
+ \new Staff { \clef bass c,, }
+ >>
+}
@end lilypond
-
-The command @code{\new} introduces a `notation context.' A notation
+The command @code{\new} introduces a @q{notation context.} A notation
context is an environment in which musical events (like notes or
@code{\clef} commands) are interpreted. For simple pieces, such
notation contexts are created automatically. For more complex pieces, it
-is best to mark contexts explicitly. This ensures that each fragment
-gets its own stave.
+is best to mark contexts explicitly.
-There are several types of contexts. @code{Staff}, @code{Voice} and
-@code{Score} handle melodic notation, while @code{Lyrics} sets lyric
+There are several types of contexts. @code{Score}, @code{Staff},
+and @code{Voice} handle melodic notation, while @code{Lyrics} sets lyric
texts and @code{ChordNames} prints chord names.
In terms of syntax, prepending @code{\new} to a music expression
sign in mathematics. The formula @math{(4+5)} is an expression, so
@math{-(4+5)} is a bigger expression.
-We can now typeset a melody with two staves
-
-@c TODO: (c) status of this Paul McCartney (?) song (let's all stand together)
+Time signatures entered in one staff affects all other staves, but
+the key signature of one staff does @emph{not} affect other
+staves@footnote{This behavior may be changed if desired; see
+@ref{Changing defaults} for details.}.
-@lilypond[fragment,quote,verbatim,ragged-right]
-\relative <<
- \new Staff {
- \time 3/4
- \clef treble
-
- e'2 d4 c2 b4 a8[ a]
- b[ b] g[ g] a2.
- }
- \new Staff {
- \clef bass
- c,,2 e4 g2.
- f4 e d c2.
- }
->>
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ <<
+ \new Staff { \clef treble \time 3/4 c }
+ \new Staff { \clef bass \key d \major c,, }
+ >>
+}
@end lilypond
-For more information on contexts see the description in
-@ref{Interpretation contexts}.
-
-
-
-@node Adding articulation marks to notes
-@section Adding articulation marks to notes
-
-@cindex articulation
-@cindex accents
-@cindex staccato
-
-Common accents can be added to a note using a dash (@samp{-}) and a
-single character
-@lilypond[fragment,quote,verbatim,relative=2]
-c-. c-- c-> c-^ c-+ c-_
-@end lilypond
-@cindex fingering
-Similarly, fingering indications can be added to a note using a dash
-(@samp{-}) and the digit to be printed
-@lilypond[fragment,quote,verbatim,relative=2]
-c-3 e-5 b-2 a-1
-@end lilypond
+@node Piano staves
+@subsection Piano staves
-Articulations and fingerings are usually placed automatically, but you
-can specify a direction using @samp{^} (up) or @samp{_} (down). You can
-also use multiple articulations on the same note. In most cases, however,
-it is best to let LilyPond determine the articulation directions.
+@cindex staff switch, manual
+@cindex cross staff voice, manual
+Piano music is typeset in two staves connected by a brace. Printing
+such a staff is similar to the polyphonic example in @ref{Multiple staves},
+but now this entire expression is inserted inside a @code{PianoStaff}:
-@lilypond[fragment,quote,verbatim,relative=2]
-c_-^1 d^. f^4_2-> e^-_+
-@end lilypond
+@example
+\new PianoStaff <<
+ \new Staff @dots{}
+ \new Staff @dots{}
+>>
+@end example
-Dynamic signs are made by adding the markings (with a backslash) to
-the note
+Here is a small example
-@lilypond[fragment,quote,verbatim,relative=2]
-c\ff c\mf
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ \new PianoStaff <<
+ \new Staff { \time 2/4 c4 e g g, }
+ \new Staff { \clef bass c,, c' e c }
+ >>
+}
@end lilypond
-@cindex dynamics
-@cindex decrescendo
-@cindex crescendo
-
-Crescendi and decrescendi are started with the commands @code{\<} and
-@code{\>}. An ending dynamic, for example @code{\f}, will finish the
-(de)crescendo, or the command @code{\!} can be used
-
-@lilypond[fragment,quote,verbatim,relative=2]
-c2\< c2\ff\> c2 c2\!
-@end lilypond
+@moreinfo
+@quotation
+See @ref{Piano music}.
+@end quotation
+@node Single staff polyphony
+@subsection Single staff polyphony
-@cindex slur
+@cindex polyphony
+@cindex multiple voices
+@cindex voices, more -- on a staff
+When different melodic lines are combined on a single staff they are
+printed as polyphonic voices; each voice has its own stems, slurs and
+beams, and the top voice has the stems up, while the bottom voice has
+them down.
-A @rglos{slur} is a curve drawn across many notes, and indicates
-legato articulation. The starting note and ending note are marked
-with @samp{(} and @samp{)}, respectively
+Entering such parts is done by entering each voice as a sequence (with
+@code{@{...@}}) and combining these simultaneously, separating the
+voices with @code{\\}
-@lilypond[fragment,quote,fragment,relative=2,verbatim]
-d4( c16) cis( d e c cis d) e( d4)
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+<<
+ { a4 g2 f4~ f4 } \\
+ { r4 g4 f2 f4 }
+>>
@end lilypond
-@cindex slurs versus ties
-A slur looks like a @rglos{tie}, but it has a different meaning. A
-tie simply makes the first note sound longer, and can only be used on
-pairs of notes with the same pitch. Slurs indicate the articulations
-of notes, and can be used on larger groups of notes. Slurs and ties
-can be nested
+For polyphonic music typesetting, spacer rests can also be convenient;
+these are rests that do not print. They are useful for filling up
+voices that temporarily do not play. Here is the same example with a
+spacer rest (@samp{s}) instead of a normal rest (@samp{r}),
-@lilypond[quote,fragment,relative=2]
-c2~( c8 fis fis4 ~ fis2 g2)
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+<<
+ { a4 g2 f4~ f4 } \\
+ { s4 g4 f2 f4 }
+>>
@end lilypond
-@cindex phrasing slurs
-Slurs to indicate phrasing can be entered with @code{\(} and
-@code{\)}, so you can have both legato slurs and phrasing slurs at the
-same time. You cannot have simultaneous slurs or simultaneous
-phrasing slurs.
+@noindent
+Again, these expressions can be nested arbitrarily.
-@lilypond[quote,fragment,relative=2,verbatim]
-a8(\( ais b c) cis2 b'2 a4 cis, c\)
+@lilypond[quote,fragment,verbatim,relative=2,fragment]
+<<
+ \new Staff <<
+ { a4 g2 f4~ f4 } \\
+ { s4 g4 f2 f4 }
+ >>
+ \new Staff <<
+ \clef bass
+ { <c g>1 ~ <c g>4 } \\
+ { e,,4 d e2 ~ e4}
+ >>
+>>
@end lilypond
-
-For more information on
-
+@moreinfo
@quotation
-@table @asis
-@item Fingering
-see @ref{Fingering instructions}.
-@item Articulations
-see @ref{Articulations}.
-@item Slurs
-see @ref{Slurs}.
-@item Phrasing slurs
-see @ref{Phrasing slurs}.
-@item Dynamics
-see @ref{Dynamics}.
-@end table
+See @ref{Basic polyphony}.
@end quotation
@node Combining notes into chords
-@section Combining notes into chords
+@subsection Combining notes into chords
@cindex chords
-Chords can be made by surrounding pitches with angle brackets.
-Angle brackets are the symbols @samp{<} and @samp{>}.
+Chords can be made by surrounding pitches with single angle brackets. Angle
+brackets are the symbols @samp{<} and @samp{>}.
-@lilypond[quote,relative=1,fragment,verbatim]
-r4 <c e g>4 <c f a>8
+@lilypond[quote,fragment,verbatim,relative=2,fragment]
+r4 <c e g>4 <c f a>2
@end lilypond
-
You can combine markings like beams and ties with chords. They must
-be placed outside the angled brackets
-
-@lilypond[quote,relative=1,fragment,verbatim]
-r4 <c e g>8[ <c f a>]~ <c f a>
-@end lilypond
-
-@example
-r4 <c e g>8\>( <c e g> <c e g> <c f a>\!)
-@end example
-
-@lilypond[quote,relative=1,fragment]
-\slurUp
-r4 <c e g>8\>( <c e g> <c e g> <c f a>\!)
-@end lilypond
+be placed outside the angle brackets
-
-@node Advanced rhythmic commands
-@section Advanced rhythmic commands
-
-@cindex pickup
-@cindex anacruse
-@cindex partial measure
-A pickup is entered with the keyword @code{\partial}. It
-is followed by a duration: @code{\partial 4} is a quarter note upstep
-and @code{\partial 8} an eighth note
-
-@lilypond[quote,relative=2,verbatim,fragment]
-\partial 8
-f8 c2 d e
-@end lilypond
-
-@cindex tuplets
-@cindex triplets
-Tuplets are made with the @code{\times} keyword. It takes two
-arguments: a fraction and a piece of music. The duration of the piece
-of music is multiplied by the fraction. Triplets make notes occupy
-2/3 of their notated duration, so a triplet has 2/3 as its fraction
-
-@lilypond[quote,relative=1,verbatim,fragment]
-\times 2/3 { f8 g a }
-\times 2/3 { c r c }
+@lilypond[quote,fragment,verbatim,relative=2,fragment]
+r4 <c e g>8[ <c f a>]~ <c f a>2
@end lilypond
-@cindex grace notes
-@cindex acciaccatura
-Grace notes are also made by prefixing a music expression with the
-keyword @code{\appoggiatura} or @code{\acciaccatura}
-@cindex appoggiatura
-@cindex acciaccatura
-
-@lilypond[quote,relative=2,verbatim,fragment]
-c4 \appoggiatura b16 c4
-c4 \acciaccatura b16 c4
+@lilypond[quote,fragment,verbatim,relative=2,fragment]
+r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
@end lilypond
-@noindent
-
-For more information on
-
-@quotation
-@table @asis
-@item Grace notes
-see @ref{Grace notes},
-@item Tuplets
-see @ref{Tuplets},
-@item Pickups
-see @ref{Partial measures}.
-@end table
-@end quotation
-
-
-@node Commenting input files
-@section Commenting input files
-
-@cindex comments
-@cindex line comment
-@cindex block comment
-A comment is a remark for the human reader of the music input; it is
-ignored while parsing, so it has no effect on the printed output.
-There are two types of comments. The percent symbol @samp{%}
-introduces a line comment; after @code{%} the rest of the line is
-ignored. A block comment marks a whole section of music
-input. Anything that is enclosed in @code{%@{} and @code{%@}} is
-ignored. The following fragment shows possible uses for comments
-
-@example
-% notes for twinkle twinkle follow
- c4 c g' g a a g2
-
-%@{
- This line, and the notes below
- are ignored, since they are in a
- block comment.
-
- g g f f e e d d c2
-%@}
-@end example
-
-@c TODO post-2.6 reorg
-@c This is good info, but I wouldn't call it a comment. IMO it should
-@c be moved somewhere else.
-
-@cindex versioning
-There is a special statement that is a kind of comment. The @code{\version}
-statement marks for which version of LilyPond the file was written.
-To mark a file for version 2.10.8, use
+@node Songs
+@section Songs
-@example
-\version "2.10.8"
-@end example
+This section introduces vocal music and simple song sheets.
-@noindent
-These annotations make future upgrades of LilyPond go more
-smoothly. Changes in the syntax are handled with a special program,
-@file{convert-ly} (see @ref{Updating files with convert-ly}), and it uses
-@code{\version} to determine what rules to apply.
+@menu
+* Printing lyrics::
+* A lead sheet::
+@end menu
@node Printing lyrics
-@section Printing lyrics
-@cindex lyrics
-
-@c TODO: (c) status of the Queen fragment.
+@subsection Printing lyrics
@cindex Lyrics
@cindex Songs
-Lyrics are entered by separating each syllable with a space
-
-@example
-I want to break free
-@end example
-
-Consider the melody
+Consider a simple melody:
-@lilypond[quote,verbatim,fragment,ragged-right]
-\relative {
- r4 c \times 2/3 { f g g }
- \times 2/3 { g4( a2) }
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+ a4 e c8 e r4
+ b2 c4( d)
}
@end lilypond
The lyrics can be set to these notes, combining both with the
-@code{\addlyrics} keyword
+@code{\addlyrics} keyword. Lyrics are entered by separating each
+syllable with a space.
-@lilypond[quote,verbatim,fragment,ragged-right]
+@lilypond[quote,ragged-right,verbatim]
<<
- \relative {
- r4 c \times 2/3 { f g g }
- \times 2/3 { g4( a2) }
+ \relative c'' {
+ a4 e c8 e r4
+ b2 c4( d)
}
- \addlyrics { I want to break free }
+ \addlyrics { One day this shall be free }
>>
@end lilypond
@cindex melisma
@cindex extender line
-@c synonyms?
-This melody ends on a @rglos{melisma}, a single syllable (`free')
+This melody ends on a @rglos{melisma}, a single syllable (@q{free})
sung to more than one note. This is indicated with an @emph{extender
-line}. It is entered as two underscores, i.e.,
-
-@example
-@{ I want to break free __ @}
-@end example
+line}. It is entered as two underscores @code{__}:
-@lilypond[fragment,quote,ragged-right]
+@lilypond[quote,ragged-right,verbatim]
<<
- \relative {
- r4 c \times 2/3 { f g g }
- \times 2/3 { g4( a2) }
+ \relative c'' {
+ a4 e c8 e r4
+ b2 c4( d)
}
- \addlyrics { I want to break free __ }
+ \addlyrics { One day this shall be free __ }
>>
@end lilypond
Similarly, hyphens between words can be entered as two dashes,
resulting in a centered hyphen between two syllables
-@example
-A -- le gri -- a
-@end example
-
-@c no ragged-right here, because otherwise the hypens get lost.
-@lilypond[fragment,quote]
+@c no ragged-right here because otherwise the hypens get lost.
+@lilypond[quote,verbatim]
<<
- \relative {
+ \relative c' {
\time 2/4
- f4 f c' c
+ f4 f c c
}
- \addlyrics { A -- le gri -- a }
+ \addlyrics { A -- le -- gri -- a }
>>
@end lilypond
-More options, like putting multiple lines of lyrics below a melody are
+@moreinfo
+@quotation
+More options, such as putting multiple stanzas below a melody, are
discussed in @ref{Vocal music}.
+@end quotation
@node A lead sheet
-@section A lead sheet
+@subsection A lead sheet
@cindex Lead sheets
@cindex chords
@cindex chord names
@c TODO: revise this, \chords { } is shorter and more intuitive.
+@c I need help for this. -gp
-In popular music, it is common to denote accompaniment with chord names.
+In popular music it is common to denote accompaniment with chord names.
Such chords can be entered like notes,
-@lilypond[quote,verbatim,ragged-right]
+@lilypond[quote,ragged-right,verbatim]
\chordmode { c2 f4. g8 }
@end lilypond
When put together, chord names, lyrics and a melody form
a lead sheet, for example,
-@example
-<<
- \chords @{ @emph{chords} @}
- @emph{the melody}
- \addlyrics @{ @emph{the text} @}
->>
-@}
-@end example
-
-@lilypond[quote,ragged-right]
+@lilypond[quote,verbatim,ragged-right]
+% FIXME: this melody needs to be changed. See my new example in 2.4.1. -gp
<<
\chords { r2 c:sus4 f }
\relative {
in @ref{Chords}.
+@node Final touches
+@section Final touches
+
+This is the final section of the tutorial; it demonstrates how to add the
+final touches to simple pieces, and provides an introduction to the rest
+of the manual.
+
+@menu
+* Version number::
+* Adding titles::
+* Absolute note names::
+* Organizing pieces with identifiers::
+* After the tutorial::
+* How to read the manual::
+@end menu
+
+
+@node Version number
+@subsection Version number
+
+@cindex versioning
+The @code{\version} statement marks for which version of LilyPond the file
+was written. To mark a file for version 2.10.1, place
+
+@example
+\version "2.10.1"
+@end example
+
+@noindent
+at the top of your LilyPond file.
+
+These annotations make future upgrades of LilyPond go more
+smoothly. Changes in the syntax are handled with a special program,
+@file{convert-ly} (see @ref{Updating files with convert-ly}), and it uses
+@code{\version} to determine what rules to apply.
+
+
@node Adding titles
-@section Adding titles
+@subsection Adding titles
-Bibliographic information is entered in a separate block, the
-@code{\header} block. The name of the piece, its composer, etc., are
-entered as an assignment, within @code{\header
-@{@tie{}@dots{}@tie{}@}}. The @code{\header} block is usually put at
-the top of the file. For example,
+The title, composer, opus number, and similar information are entered
+in the @code{\header} block. This exists outside of the main
+music expression; the @code{\header} block is usually placed underneath
+the @ref{Version number}.
@example
+\version "2.10.1"
\header @{
- title = "Miniature"
- composer = "Igor Stravinsky"
+ title = "Symphony"
+ composer = "Me"
+ opus = "Op. 9"
@}
-@{ @dots{} @}
+@{
+ @dots{} music @dots{}
+@}
@end example
-
When the file is processed, the title and composer are printed above
the music. More information on titling can be found in @ref{Creating
titles}.
-@node Single staff polyphony
-@section Single staff polyphony
+@node Absolute note names
+@subsection Absolute note names
-@cindex polyphony
-@cindex multiple voices
-@cindex voices, more -- on a staff
-When different melodic lines are combined on a single staff they are
-printed as polyphonic voices; each voice has its own stems, slurs and
-beams, and the top voice has the stems up, while the bottom voice has
-them down.
+So far we have always used @code{\relative} to define pitches. This is
+the easiest way to enter most music, but another way of defining pitches
+exists: absolute mode.
-Entering such parts is done by entering each voice as a sequence (with
-@code{@{...@}}), and combining these simultaneously, separating the
-voices with @code{\\}
+If you omit the @code{\relative}, LilyPond treats all pitches as
+absolute values. A @code{c'} will always mean middle C, a @code{b} will
+always mean the note one step below middle C, and a @code{g,} will
+always mean the note on the bottom staff of the bass clef.
-@lilypond[quote,verbatim,relative=2,fragment]
-<< { a4 g2 f4~ f4 } \\
- { r4 g4 f2 f4 } >>
+@lilypond[quote,verbatim,ragged-right]
+{
+ \clef bass
+ c' b g, g,
+ g, f, f c'
+}
@end lilypond
-For polyphonic music typesetting, spacer rests can also be convenient;
-these are rests that do not print. They are useful for filling up
-voices that temporarily do not play. Here is the same example with a
-spacer rest (@code{s}) instead of a normal rest (@code{r}),
+Here is a four-octave scale:
-@lilypond[quote,verbatim,relative=2,fragment]
-<< { a4 g2 f4~ f4 } \\
- { s4 g4 f2 f4 } >>
+@lilypond[quote,verbatim,ragged-right]
+{
+ \clef bass
+ c, d, e, f,
+ g, a, b, c
+ d e f g
+ a b c' d'
+ \clef treble
+ e' f' g' a'
+ b' c'' d'' e''
+ f'' g'' a'' b''
+ c'''1
+}
@end lilypond
-@noindent
-Again, these expressions can be nested arbitrarily
+As you can see, writing a melody in the treble clef involves a lot of
+quote ' marks. Consider this fragment from Mozart:
-@lilypond[quote,fragment,verbatim,relative=2,fragment]
-<<
- \new Staff <<
- { a4 g2 f4~ f4 } \\
- { s4 g4 f2 f4 }
- >>
- \new Staff <<
- \clef bass
- { <c g>1 ~ <c g>4 } \\
- { e,,4 d e2 ~ e4}
- >>
->>
+@lilypond[quote,verbatim,ragged-right]
+{
+ \key a \major
+ \time 6/8
+ cis''8. d''16 cis''8 e''4 e''8
+ b'8. cis''16 b'8 d''4 d''8
+}
@end lilypond
-More features of polyphonic typesetting are described in this manual
-in section @ref{Basic polyphony}.
+All these quotes makes the input less readable and it is a source of
+errors. With @code{\relative}, the previous example is much easier
+to read:
-
-@node Piano staves
-@section Piano staves
-
-@cindex staff switch, manual
-@cindex cross staff voice, manual
-Piano music is typeset in two staves connected by a brace. Printing
-such a staff is similar to the polyphonic example in @ref{More staves},
-
-@example
-<< \new Staff @{ @dots{} @}
- \new Staff @{ @dots{} @} >>
-@end example
-
-@noindent
-but now this entire expression must be interpreted as a
-@code{PianoStaff}
-
-@example
-\new PianoStaff << \new Staff @dots{} >>
-@end example
-
-Here is a small example
-
-@lilypond[quote,verbatim,relative=1,fragment]
-\new PianoStaff <<
- \new Staff { \time 2/4 c4 c g' g }
- \new Staff { \clef bass c,, c' e c }
->>
+@lilypond[quote,verbatim,ragged-right]
+\relative c'' {
+ \key a \major
+ \time 6/8
+ cis8. d16 cis8 e4 e8
+ b8. cis16 b8 d4 d8
+}
@end lilypond
-More information on formatting piano music is given in @ref{Piano music}.
+If you make a mistake with an octave mark (@code{'} or @code{,}) while
+working in @code{\relative} mode, it is very obvious -- many notes will
+be in the wrong octave. When working in absolute mode, a single mistake
+will not be as visible, and will not be as easy to find.
+
+However, absolute mode is useful for music which has large intervals, and
+is extremely useful for computer-generated LilyPond files.
-@node Organizing larger pieces
-@section Organizing larger pieces
+@node Organizing pieces with identifiers
+@subsection Organizing pieces with identifiers
When all of the elements discussed earlier are combined to produce
-larger files, the @code{\score} blocks get a lot bigger because the
-music expressions are longer, and, in the case of polyphonic music,
-more deeply nested. Such large expressions can become unwieldy.
+larger files, the music expressions get a lot bigger. In polyphonic
+music with many staves, the input files can become very confusing. We can
+reduce this confusion by using @emph{identifiers}.
-By using variables, also known as identifiers, it is possible to break
-up complex music expressions. An identifier is assigned as follows
+With identifiers (also known as variables or macros), we can break up
+complex music expressions. An identifier is assigned as follows
@example
namedMusic = @{ @dots{} @}
@end example
-@noindent
-The contents of the music expression @code{namedMusic}, can be used
-later by preceding the name with a backslash, i.e., @code{\namedMusic}.
-In the next example, a two-note motive is repeated two times by using
-variable substitution
-
-@lilypond[quote,ragged-right,verbatim,nofragment]
-seufzer = {
- e'4( dis'4)
+The contents of the music expression @code{namedMusic} can be used
+later by placing a backslash in front of the name
+(@code{\namedMusic}, just like a normal LilyPond command). Identifiers
+must be defined @emph{before} the main music expression.
+
+@lilypond[quote,verbatim,ragged-right]
+violin = \new Staff { \relative c'' {
+ a4 b c b
+}}
+cello = \new Staff { \relative c {
+ \clef bass
+ e2 d
+}}
+{
+ <<
+ \violin
+ \cello
+ >>
}
-{ \seufzer \seufzer }
@end lilypond
-The name of an identifier should have alphabetic characters only: no
-numbers, underscores, or dashes. The assignment should be outside of
-running music.
+@noindent
+The name of an identifier must have alphabetic characters only: no
+numbers, underscores, or dashes.
It is possible to use variables for many other types of objects in the
input. For example,
@end example
Depending on its contents, the identifier can be used in different
-places. The following example uses the above variables
+places. The following example uses the above variables:
@example
\paper @{
@{ c4^\name @}
@end example
-More information on the possible uses of identifiers is given in the
-technical manual, in @ref{Input variables and Scheme}.
-@c fixme: the ref is too technical.
-
-
-@node An orchestral part
-@section An orchestral part
-
-In orchestral music, all notes are printed twice. Once in a part for
-the musicians, and once in a full score for the conductor. Identifiers can
-be used to avoid double work. The music is entered once, and stored in
-a variable. The contents of that variable is then used to generate
-both the part and the full score.
-
-It is convenient to define the notes in a special file. For example,
-suppose that the file @file{horn-music.ly} contains the following part
-of a horn/@/bassoon duo
-
-@example
-hornNotes = \relative c @{
- \time 2/4
- r4 f8 a cis4 f e d
-@}
-@end example
-
-@noindent
-Then, an individual part is made by putting the following in a file
-
-@example
-\include "horn-music.ly"
-\header @{
- instrument = "Horn in F"
-@}
-
-@{
- \transpose f c' \hornNotes
-@}
-@end example
-
-The line
-
-@example
-\include "horn-music.ly"
-@end example
-
-@noindent
-substitutes the contents of @file{horn-music.ly} at this position in
-the file, so @code{hornNotes} is defined afterwards. The command
-@code{\transpose f@tie{}c'} indicates that the argument, being
-@code{\hornNotes}, should be transposed by a fifth upwards. Sounding
-@samp{f} is denoted by notated @code{c'}, which corresponds with the
-tuning of a normal French Horn in@tie{}F. The transposition can be seen
-in the following output
-
-@lilypond[quote,ragged-right]
-\transpose f c' \relative c {
- \time 2/4
- r4 f8 a cis4 f e d
-}
-@end lilypond
-
-In ensemble pieces, one of the voices often does not play for many
-measures. This is denoted by a special rest, the multi-measure
-rest. It is entered with a capital @samp{R} followed by a duration
-(@code{1}@tie{}for a whole note, @code{2}@tie{}for a half note,
-etc.). By multiplying the
-duration, longer rests can be constructed. For example, this rest
-takes 3@tie{}measures in 2/4 time
-
-@example
-R2*3
-@end example
-
-When printing the part, multi-rests
-must be condensed. This is done by setting a run-time variable
-
-@example
-\set Score.skipBars = ##t
-@end example
-
-@noindent
-This command sets the property @code{skipBars} in the
-@code{Score} context to true (@code{##t}). Prepending the rest and
-this option to the music above, leads to the following result
-
-@lilypond[quote,ragged-right]
-\transpose f c' \relative c {
- \time 2/4
- \set Score.skipBars = ##t
- R2*3
- r4 f8 a cis4 f e d
-}
-@end lilypond
-
-
-The score is made by combining all of the music together. Assuming
-that the other voice is in @code{bassoonNotes} in the file
-@file{bassoon-music.ly}, a score is made with
-
-@example
-\include "bassoon-music.ly"
-\include "horn-music.ly"
-
-<<
- \new Staff \hornNotes
- \new Staff \bassoonNotes
->>
-@end example
-
-@noindent
-leading to
-
-@lilypond[quote,ragged-right]
-\relative c <<
- \new Staff {
- \time 2/4 R2*3
- r4 f8 a cis4 f e d
- }
- \new Staff {
- \clef bass
- r4 d,8 f | gis4 c | b bes |
- a8 e f4 | g d | gis f
- }
->>
-@end lilypond
-
-More in-depth information on preparing parts and scores can be found
-in the notation manual; see @ref{Orchestral music}.
-
-Setting run-time variables (`properties') is discussed in
-@ref{Changing context properties on the fly}.
-
@node After the tutorial
-@section After the tutorial
+@subsection After the tutorial
After finishing the tutorial, you should probably try writing a
-piece or two. Start with one of the @ref{Example templates} and
+piece or two. Start with one of the @ref{Templates} and
add notes. If you need any notation that was not covered in the
tutorial, look at the Notation Reference, starting with
@ref{Basic notation}. If you want to write for an instrument
-ensemble which is not covered in the @ref{Example templates},
+ensemble which is not covered in the templates,
take a look at @ref{Extending the templates}.
Once you have written a few short pieces, read the rest of
now, and come back to them after you have more experience.
+@node How to read the manual
+@subsection How to read the manual
+
+As we saw in @ref{How to read the tutorial}, many examples in the
+tutorial omitted a @code{\relative c'' @{ ... @}} around the printed
+example.
+
+In the rest of the manual, we are much more lax about the
+printed examples: sometimes they may have omitted a
+@code{\relative c'' @{ ... @}}, but in other times a different initial
+pitch may be used (such as @code{c'} or @code{c,,}), and in some cases
+the whole example is in absolute note mode! However, ambiguities like
+this only exist where the pitches are not important. In any example
+where the pitch matters, we have explicitly stated our @code{\relative}
+our our absolute-mode @code{@{ @}}.
+
+If you are still confused about the exact LilyPond input that was
+used in an example, read the HTML version (if you are not already doing
+so) and click on the picture of the music. This will display the exact
+input that LilyPond used to generate this manual.
+
objects; simply replace @code{TextScript} with the name of
another object.
-To find the object name, look at the ``@strong{see also}'' at
+To find the object name, look at the @qq{@strong{see also}} at
bottom of the relevant documentation page. For example, at
the bottom of @ref{Dynamics}, we see
@item
Setting the @code{transparent} property will cause an object to be printed
-in `invisible ink': the object is not printed, but all its other
+in @q{invisible ink}: the object is not printed, but all its other
behavior is retained. The object still takes up space, it takes part in
collisions, and slurs, ties, and beams can be attached to it.
systems, they will take up more space than one system with
the volta repeats and another system without.
-Another example is moving dynamics which ``stick out'' of
+Another example is moving dynamics which @qq{stick out} of
a system.
@lilypond[verbatim,quote,fragment]
* Style sheets::
* Updating old files::
* Troubleshooting (taking it all apart)::
+* Minimal examples::
@end menu
using a few years ago. @code{convert-ly} requires you to declare
which version of LilyPond you used.
-@item @strong{Include checks}: @ref{Bar check} and @ref{Octave check}. If
-you
+@item @strong{Include checks}: @ref{Bar check}, @ref{Octave check} and
+@ref{Barnumber check}. If you
include checks every so often, then if you make a mistake, you can pinpoint
-it quicker. How often is ``every so often''? It depends on the complexity
+it quicker. How often is @qq{every so often}? It depends on the complexity
of the music. For very simple music, perhaps just once or twice. For
very complex music, perhaps every bar.
either in the music
itself or in the output you desire, it's often good to write only one bar
per line. Saving screen space by cramming eight bars per line just isn't
-worth it if you have to `debug' your files.
+worth it if you have to @q{debug} your files.
@item @strong{Comment your files}. Use either bar numbers (every so often)
or
-references to musical themes (``second theme in violins,'' ``fourth
+references to musical themes (@qq{second theme in violins,} ``fourth
variation'', etc). You may not need comments when you're writing the piece
for the first time, but if you want to go back to change something two or
three years later, or if you pass the source over to a friend, it will
is quite easy to do.
Let's look at an example. Don't worry if you don't understand
-the parts with all the #(). This is explained in
+the parts with all the @code{#()}. This is explained in
@ref{Advanced tweaks with Scheme}.
@lilypond[quote,verbatim,ragged-right]
to use them in another piece. We could simply copy-and-paste them
at the top of every file, but that's an annoyance. It also leaves
those definitions in our music files, and I personally find all
-the #() somewhat ugly. Let's hide them in another file:
+the @code{#()} somewhat ugly. Let's hide them in another file:
@example
%%% save this to a file called "definitions.ly"
This approach can be useful even if you are only producing
one set of parts. I use half a dozen different
-``style sheet'' files for my projects. I begin every music
+@qq{style sheet} files for my projects. I begin every music
file with @code{\include "../global.ly"}, which contains
@example
@code{convert-ly}. For details about how to run this program, see
@ref{Updating files with convert-ly}.
-Unforunately, @code{convert-ly} cannot handle all input changes. It
+Unfortunately, @code{convert-ly} cannot handle all input changes. It
takes care of simple search-and-replace changes (such as @code{raggedright}
becoming @code{ragged-right}), but some changes are too
complicated. The syntax changes that @code{convert-ly} cannot handle
For example, in LilyPond 2.4 and earlier, accents and non-English
letters were entered using LaTeX -- for example,
"@code{No\"el}" (this would print the French word for
-`Christmas'). In LilyPond 2.6 and above, the special
+@q{Christmas}). In LilyPond 2.6 and above, the special
"@code{ë}" must be entered directly into the LilyPond file as an
UTF-8 character. @code{convert-ly} cannot change all the LaTeX
special characters into UTF-8 characters; you must manually update
Now start slowly uncommenting more and more of the
@code{bass} part until you find the problem line.
+Another very useful debugging technique is constructing
+@ref{Minimal examples}.
+
+
+@node Minimal examples
+@section Minimal examples
+
+A minimal example is an example which is small as possible. These
+examples are much easier to understand than long examples. Minimal
+examples are used for
+
+@itemize
+@item Bug reports
+@item Sending a help request to mailists
+@item Adding an example to the @uref{http://lsr@/.dsi@/.unimi/2.it/,LilyPond
+Snippet Repository}
+@end itemize
+
+To construct an example which is as small as possible, the rule is
+quite simple: remove anything which is not necessary. When trying to
+remove unnecessary parts of a file, it is a very good idea to comment
+out lines instead of deleting them. That way, if you discover that you
+actually @emph{do} need some lines, you can uncomment them, instead of
+typing them in from scratch.
+
+There are two exceptions to the @qq{as small as possible} rule:
+
+@itemize
+@item Include the @code{\version} number.
+@item If possible, use @code{\paper@{ ragged-right=##t @}} at the
+top of your example.
+@end itemize
+
+The whole point of a minimal example is to make it easy to read:
+
+@itemize
+@item Avoid using complicated notes, keys, or time signatures, unless you
+wish to demonstrate something is about the behavior of those items.
+@item Do not use @code{\override} commands unless that is the point of the
+example.
+@end itemize
+
Harald Wellmann
Henrik Frisk
Hernán J. González
+James Kilfinger
Johannes Schindelin
John Williams
J. Leung
projects / lilypond.git / commitdiff