From: John Mandereau <john.mandereau@gmail.com>
Date: Sat, 9 Aug 2008 16:23:43 +0000 (+0200)
Subject: Merge branch 'master' into lilypond/translation
X-Git-Tag: release/2.11.56-1~2^2~43
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=7ffb44d7dbcd7bcf66ab0b0ef64515af416f3709;hp=930597f24f94aade895376441deb0c2435aa9e95;p=lilypond.git

Merge branch 'master' into lilypond/translation

* master: (41 commits)
  Update predefined fret diagrams and documentation
  Indexes from Ralph.
  Indexes from Ralph.
  Compile fix
  Patch 0006 from John
  Patch 0005 from John
  Patch 0003 from John
  Patch 0002 from John
  Patch 0001 from John
  Compile fix
  Some additions to NR 1.8 "Text"
  Compile fix in NR 1.8
  Some additions to NR 1.8 "Text"
  Revert fretted-strings.itely
  Saving status that won't build docs
  Update for Expressive and Staff
  GDP NR 5.5.1 Amend layer details
  Fix broken documentation file
  Add predefined fret diagrams to FretBoards context
  GDP LM 4.3.1 Work around for layer
  ...
---

diff --git a/Documentation/es/user/text.itely b/Documentation/es/user/text.itely
index d2db60d398..6d6ed3dacc 100644
--- a/Documentation/es/user/text.itely
+++ b/Documentation/es/user/text.itely
@@ -325,7 +325,7 @@ usando la sintaxis específica del modo de @code{\markup}.
 
 @menu
 * Text markup introduction::    
-* Common markup commands::      
+* Selecting font and font size::      
 * Text alignment::              
 * Graphic notation inside markup::  
 * Music notation inside markup::  
@@ -454,8 +454,8 @@ Los errores de sintaxis para el modo de marcado a menudo producen
 confusión.
 
 
-@node Common markup commands
-@subsubsection Common markup commands
+@node Selecting font and font size
+@subsubsection Selecting font and font size
 
 UNTRANSLATED NODE: IGNORE ME
 
diff --git a/Documentation/fr/user/input.itely b/Documentation/fr/user/input.itely
index 196df08b3c..5515f12a0e 100644
--- a/Documentation/fr/user/input.itely
+++ b/Documentation/fr/user/input.itely
@@ -11,8 +11,8 @@
 
 @c Translators: Jean-Charles Malahieude
 
-@node Input syntax
-@chapter Input syntax
+@node General input and output
+@chapter General input and output
 
 UNTRANSLATED NODE: IGNORE ME
 
diff --git a/Documentation/fr/user/introduction.itely b/Documentation/fr/user/introduction.itely
index 6de37214c5..b9c29a0509 100644
--- a/Documentation/fr/user/introduction.itely
+++ b/Documentation/fr/user/introduction.itely
@@ -1,7 +1,7 @@
 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
 @c This file is part of lilypond-kearning.tely
 @ignore
-    Translation of GIT committish: 27af34a245b02a6b89c9af3becefcfe676b2e19d
+    Translation of GIT committish: f8b1d1c16ff9c8d89e48175b5881ec039a0fae3b
 
     When revising a translation, copy the HEAD committish of the
     version that you are working on.  See TRANSLATION for details.
@@ -316,7 +316,7 @@ haut (droite).
 \new Score \with {
    \override SpacingSpanner #'spacing-increment = #3
    \override TimeSignature #'transparent = ##t
-} \relative {
+} \relative c' {
    \stemDown <e g b>4_>-\arpeggio
    \override Arpeggio #'direction = #RIGHT
    \stemUp <e g b>4^>-\arpeggio
@@ -439,9 +439,9 @@ pour les têtes de notes, le graveur de têtes de note
 \include "engraver-example.ily"
 
 \score {
-   \topVoice
-   \layout {
-   \context {
+  \topVoice
+  \layout {
+    \context {
       \Voice
       \remove "Stem_engraver"
       \remove "Phrasing_slur_engraver"
@@ -449,8 +449,8 @@ pour les têtes de notes, le graveur de têtes de note
       \remove "Script_engraver"
       \remove "Beam_engraver"
       \remove "Auto_beam_engraver"
-   }
-   \context {
+    }
+    \context {
       \Staff
       \remove "Accidental_engraver"
       \remove "Key_engraver"
@@ -459,8 +459,8 @@ pour les têtes de notes, le graveur de têtes de note
       \remove "Time_signature_engraver"
       \remove "Staff_symbol_engraver"
       \consists "Pitch_squash_engraver"
-   }
-}
+    }
+  }
 }
 @end lilypond
 
@@ -592,7 +592,7 @@ notation de plus haut niveau.
 
 @seealso
 
-Program reference: @rinternals{Contexts}.
+Référence du programme: @rinternals{Contexts}.
 
 @lilypond[quote,ragged-right]
 \include "engraver-example.ily"
@@ -645,7 +645,7 @@ de petits fragments de musique pour en former de plus grands, on peut
 exprimer de la musique plus complexe.  Par exemple
 
 @lilypond[quote,verbatim,fragment,relative=1]
-c4
+f4
 @end lilypond
 
 @noindent
@@ -739,7 +739,76 @@ La notation polyphonique et la musique pour piano peuvent également
 être générées.  L'exemple suivant associe quelques constructions
 plus exotiques :
 
-@lilypondfile[quote,ragged-right]{screech-boink.ly}
+@lilypond[quote]
+\header {
+  title = "Screech and boink"
+  subtitle = "Random complex notation"
+  composer = "Han-Wen Nienhuys"
+}
+
+\score {
+  \context PianoStaff <<
+    \new Staff = "up" {
+      \time 4/8
+      \key c \minor
+      << {
+        \revert Stem #'direction
+        \change Staff = down
+        \set subdivideBeams = ##t
+        g16.[
+          \change Staff = up
+          c'''32
+          \change Staff = down
+          g32
+          \change Staff = up
+          c'''32
+          \change Staff = down
+          g16]
+        \change Staff = up
+        \stemUp
+        \set followVoice = ##t
+        c'''32([ b''16 a''16 gis''16 g''32)]
+      } \\ {
+        s4 \times 2/3 { d'16[ f' g'] } as'32[ b''32 e'' d'']
+      } \\ {
+        s4 \autoBeamOff d''8.. f''32
+      } \\ {
+        s4 es''4
+      } >>
+    }
+
+    \new Staff = "down" {
+      \clef bass
+      \key c \minor
+      \set subdivideBeams = ##f
+      \override Stem  #'french-beaming = ##t
+      \override Beam  #'thickness = #0.3
+      \override Stem  #'thickness = #4.0
+      g'16[ b16 fis16 g16]
+      << \makeClusters {
+        as16 <as b>
+        <g b>
+        <g cis>
+      } \\ {
+        \override Staff.Arpeggio  #'arpeggio-direction =#down
+        <cis, e, gis, b, cis>4\arpeggio
+      }
+    >> }
+  >>
+  \midi {
+    \context {
+      \Score
+      tempoWholesPerMinute = #(ly:make-moment 60 8)
+    }
+  }
+  \layout {
+    \context {
+      \Staff
+      \consists Horizontal_bracket_engraver
+    }
+  }
+}
+@end lilypond
 
 Les extraits exposés ici ont tous été écrits à la main, mais ce n'est
 pas une obligation.  Puisque le moteur de formatage est en grande
@@ -764,33 +833,21 @@ musique et du texte dans les documents.
 Cette partie présente les différents volumes de la documentation.
 
 @c leave these lines wrapping around.  It's some texinfo 4.12 thing. -gp
+@c This is actually a limitation of texi2html. -jm
 @menu
-* About the Learning Manual (LM)::  introduction à LilyPond, ce volume
-  explique en profondeur comment créer de la notation.
+* About the Learning Manual (LM)::  introduction à LilyPond, ce manuel explique aux débutants la création de partitions.
 
-* About the Music Glossary (MG)::  ce volume explique de nombreux termes
-  musicaux et en donne la traduction dans d'autres langues.
+* About the Music Glossary (MG)::  ce document explique de nombreux termes musicaux et en donne la traduction dans d'autres langues.
 
-* About the Notation Reference (NR)::  ce volume représente le  cœur de
-  la documentation.  Il fournit des informations détaillées sur la
-  manière de créer de la notation.  La lecture de cet ouvrage requiert
-  une bonne compréhension des concepts exposés dans le manuel
-  d'initiation. 
+* About the Notation Reference (NR)::  ce manuel représente la partie la plus volumineuse de la documentation.  Il fournit tous les détails sur la création de notation musicale.  La lecture de cet ouvrage requiert une bonne compréhension des concepts exposés dans le manuel d'initiation.
 
-* About the Application Usage (AU)::  ce volume traite des différentes
-  composantes de LilyPond ainsi que des particularités selon les
-  environements.
+* About the Application Usage (AU)::  ce manuel aborde l'exécution des programmes LilyPond et les particularités dépendant du système d'exploitation.
 
-* About the Snippet List (SL)::  ce volume constitue une collection
-  d'extraits réalisés avec LilyPond.
+* About the Snippet List (SL)::  ce document rassemble une collection d'extraits de code LilyPond.
 
-* About the Internals Reference (IR)::  ce volume est la source
-  d'information sur le fonctionnement interne de LilyPond.  Il constitue
-  la base des ressources nécessaires à l'élaboration de retouches.
+* About the Internals Reference (IR)::  ce manuel constitue une source d'information sur le fonctionnement interne de LilyPond.  C'est une référence complète pour l'élaboration de retouches.
 
-* Other documentation::         d'autres sources de documentation sont
-  disponibles, telles que les notes d'actualité et les archives des
-  listes de diffusion.
+* Other documentation::          d'autres sources de documentation sont disponibles, telles que les notes de nouveautés et les archives des listes de diffusion.
 
 @end menu
 
@@ -805,29 +862,25 @@ de manière linéaire.
 @itemize
 
 @item
-@ref{Introduction} : 
-le pourquoi du comment de LilyPond.
+@ref{Introduction} : le pourquoi du comment de LilyPond.
 
 @item
-@ref{Tutorial} :
-introduction en douceur à la typographie musicale.
-Les utilisateurs débutants sont invités à commencer ici.
+@ref{Tutorial} : introduction en douceur à la typographie musicale.
+Les utilisateurs débutants sont invités à commencer par ce chapitre.
 
 @item
-@ref{Fundamental concepts} :
-concepts généraux du format de fichier @code{ly} spécifique à
-LilyPond.  Si vous n'êtes pas certain de l'endroit où placer une
-commande, lisez ce chapitre !
+@ref{Fundamental concepts} : concepts généraux du format de fichier
+@code{ly} spécifique à LilyPond.  Si vous n'êtes pas certain de
+l'endroit où placer une commande, lisez ce chapitre !
 
 @item
-@ref{Tweaking output} :
-introduction aux retouches de gravure avec LilyPond.
+@ref{Tweaking output} : introduction aux retouches de gravure avec
+LilyPond.
 
 @item
-@ref{Working on LilyPond projects} :
-utilisations pratiques de LilyPond, et conseils
-afin d'éviter les problèmes les plus courants.  À lire absolument avant
-de se lancer dans des travaux d'envergure.
+@ref{Working on LilyPond projects} : utilisation pratique de LilyPond,
+conseils généraux, prévention et résolution des problèmes les plus
+courants.  À lire avant de se lancer dans des travaux d'envergure !
 
 @end itemize
 
@@ -837,16 +890,14 @@ vos besoins :
 @itemize
 
 @item
-@ref{Templates} 
-de pièces LilyPond.  Copiez et collez un modèle
-dans un fichier, ajoutez les notes, et c'est prêt !
+@ref{Templates} de pièces LilyPond.  Copiez et collez un modèle dans
+un fichier, ajoutez les notes, et c'est prêt !
 
 @item
-@ref{Scheme tutorial} :
-courte introduction à Scheme, le langage de programmation
-utilisé dans les fonctions de musique.  Ces quelques lignes vous
-aideront à construire des retouches avancées ; nombre d'utilisateurs n'ont
-jamais touché à Scheme.
+@ref{Scheme tutorial} : courte introduction à Scheme, le langage de
+programmation utilisé dans les fonctions de musique.  Ces quelques
+lignes vous aideront à construire des retouches avancées ; nombre
+d'utilisateurs n'ont jamais touché à Scheme.
 
 @end itemize
 
@@ -854,21 +905,17 @@ jamais touché à Scheme.
 @node About the Music Glossary (MG)
 @unnumberedsubsec About the Music Glossary (MG)
 
-@itemize
 @cindex jargon
 @cindex terminologie
 @cindex langues étrangères
 @cindex langue
-@cindex langag
+@cindex langage
  
-@ref{Top,Music Glossary,,music-glossary} : explication des termes
-musicaux et traduction dans diverses langues.  Il est
-également disponible au format PDF. 
-Si vous n'êtes pas familier avec la notation musicale ou la
-terminologie, il est conseillé de consulter le glossaire, notamment
-pour les parties non encore traduites de la documentation.
-
-@end itemize
+@ref{Top,Music Glossary,,music-glossary,Glossaire musical} :
+explication des termes musicaux et traduction dans diverses langues.
+Si vous n'êtes pas familier avec la notation et la terminologie
+musicales, il est conseillé de consulter le glossaire, notamment pour
+les parties non encore traduites de la documentation.
 
 
 @node About the Notation Reference (NR)
@@ -876,105 +923,103 @@ pour les parties non encore traduites de la documentation.
 
 Ce volume détaille toutes les commandes LilyPond produisant une notation
 musicale.  La lecture de cet ouvrage requiert une bonne compréhension des
-concepts exposés dans le manuel d'apprentissage.
+concepts exposés dans le manuel d'initiation.
 
 @itemize
 
+@c Normalement, il est impossible d'utiliser deux points en français,
+@c car une référence externe doit se terminer par un signe de
+@c ponctuation dans la format Info.  Cependant, Info
+@c n'internationalise pas encore des documents Info, donc nous n'en
+@c avons rien à faire pour l'instant. -jm
 @item
-@ruser{Musical notation} :
-sujets groupés par type de notation.  Cette partie
-détaille la notation de base, qui sera utile dans la plupart des
-projets de partition.
+@ruser{Musical notation} : cette partie décrit la notation de base,
+qui sera utile dans la plupart des projets de partition.  Les sujets
+sont groupés par type de notation.
 
 @item
-@ruser{Specialist notation} :
-sujets groupés par type de notation.  Cette partie détaille
-des spécificités concernant certains instruments ou la voix.
+@ruser{Specialist notation} : cette partie détaille des éléments de
+notation spécifiques à certains instruments ou styles.  Les sujets
+sont groupés par type de notation.
 
 @item
-@ruser{Input syntax} :
-informations généralistes quant aux fichiers LilyPond et
-comment contrôler les sorties.
+@ruser{General input and output} : informations générales sur les
+fichiers source LilyPond et le contrôle des sorties.
 
 @item
-@ruser{Spacing issues} :
-sujets affectant la sortie globale, comme sélectionner
-la taille de papier ou spécifier les sauts de page.
+@ruser{Spacing issues} : différents aspects de l'espacement selon les
+axes et échelles, par exemple la sélection de la taille de papier, ou
+la gestion des sauts de page.
 
 @item
-@ruser{Changing defaults} :
-comment, grace aux retouches, obtenir de Lilypond
-presque tout ce que vous désirez.
+@ruser{Changing defaults} : ce chapitre est une référence des
+différentes formes de retouches, qui permettent d'obtenir de Lilypond
+(presque) tout ce que vous désirez.
 
 @item
-@ruser{Interfaces for programmers} :
-comment créer des fonctions de musique à l'aide de Scheme.
+@ruser{Interfaces for programmers} :.création de fonctions de musique
+à l'aide de Scheme.
 
 @end itemize
 
-Ce volume contient aussi des annexes que vous pouvez consulter au gré de
-vos besoins :
+Les annexes de ce manuel contiennent entre autres des tableaux de
+référence pratiques.
 
 @itemize
 
 @item
-@ruser{Literature list} :
-choix de livres de référence utiles pour ceux qui veulent
-en savoir plus sur la notation et la gravure.
+@ruser{Literature list} : choix de livres de référence, pour en savoir
+plus sur la notation et la gravure.
 
 @item
-@ruser{Notation manual tables} :
-ensemble de tableaux montrant les noms d'accord, les
-instruments MIDI, les noms de couleur, et la police Feta.
+@ruser{Notation manual tables} : tableaux montrant les noms d'accord,
+les instruments MIDI, les noms de couleur, et la police Feta.
 
 @item
-@ruser{Cheat sheet} :
-référence pratique des commandes LilyPond les plus courantes.
+@ruser{Cheat sheet} : référence pratique des commandes LilyPond les
+plus courantes.
 
 @item
-@ruser{LilyPond command index} :
-index de toutes les @code{\commandes} LilyPond.
+@ruser{LilyPond command index} : index de toutes les @code{\commandes}
+LilyPond.
 
 @item
-@ruser{LilyPond index} :
-un index complet.
+@ruser{LilyPond index} : un index complet.
 
 @end itemize
 
+
 @node About the Application Usage (AU)
 @unnumberedsubsec About the Application Usage (AU)
 
-Ce volume explique l'exécution du programme et l'intégration de
+Ce manuel explique l'exécution des programmes et l'intégration de
 partitions LilyPond dans d'autres programmes.
 
 @itemize
 
 @item
-@rprogram{Install} :
-comment installer  de LilyPond, et pour ceux que cela intéresse,
-comment le compiler.
+@rprogram{Install} : installation --- et éventuellement compilation ---
+de LilyPond.
 
 @item
-@rprogram{Setup} :
-comment configurer votre ordinateur pour une utilisation optimale
-de LilyPond, y compris avec certains éditeurs de tecte.
+@rprogram{Setup} : configuration de votre système pour une utilisation
+optimale de LilyPond, comprenant l'utilisation d'environnements
+adaptés pour certains éditeurs de tecte.
 
 @item
-@rprogram{Running LilyPond} :
-comment lancer LilyPond et ses programmes auxiliaires.  De
-plus, cette partie explique comment effectuer la mise à jour de fichiers
-source écrits avec d'anciennes versions de LilyPond.
+@rprogram{Running LilyPond} : exécution de LilyPond et de ses
+programmes auxiliaires.  De plus, cette partie explique comment
+effectuer la mise à jour de fichiers source écrits avec d'anciennes
+versions de LilyPond.
 
 @item
-@rprogram{LilyPond-book} :
-comment créer des documents intégrant des exemples musicaux,
-comme ce manuel.
+@rprogram{LilyPond-book} : création de documents intégrant des
+extraits musicaux, comme ce manuel.
 
 @item
-@rprogram{Converting from other formats} :
-comment exécuter les programmes de conversion.  Ces programmes sont
-livrés avec le paquetage LilyPond, et convertissent divers formats
-musicaux vers le format @code{.ly}.
+@rprogram{Converting from other formats} : utilisation des programmes
+de conversion.  Ces programmes sont livrés avec le paquetage LilyPond,
+et convertissent divers formats de musique vers le format @code{.ly}.
 
 @end itemize
 
@@ -985,44 +1030,41 @@ musicaux vers le format @code{.ly}.
 @cindex snippets
 @cindex LSR
 
-@c FIXME: check on kainhofer.
-@ref{Top,LilyPond Snippet List,,lilypond-snippets} :
+@ref{Top,LilyPond Snippet List,,lilypond-snippets,Exemples de code} :
 il s'agit d'une sélection de petits exemples montrant des trucs,
 astuces et fonctionnalités particulières de LilyPond, issus de
-@uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}, abrégé
-sous la forme de LSR.  Ils sont dans le domaine public.
+@uref{http://lsr@/.dsi@/.unimi@/.it,LilyPond Snippet Repository}
+(LSR).  Tous ces exemples sont dans le domaine public.
 
-Notez bien que cette annexe n'est en aucune manière un mirroir du LSR.
-Dans la mesure où le LSR repose sur une version stable de LilyPond, un
-exemple qui illustrerait de nouvelles fonctionnalités de la version de
-développement devrait y être ajouté isolément. C'est la raison pour
-laquelle vous le trouverez alors dans le répertoire @file{input/new/}
-des sources de LilyPond.
+Notez bien que cette annexe n'est en aucune manière un miroir ou même
+une partie du LSR.  Dans la mesure où le LSR repose sur une version
+stable de LilyPond, les exemples illustrant des fonctionnalités
+introduites dans la dernière version de développement ne peuvent y
+figurer ; c'est pourquoi vous les trouverez dans le répertoire
+@file{input/new/} des sources de LilyPond.
 
 La liste des exemples correspondant à chacun des sous-chapitres du
-Manuel de notation est accessible par un lien au paragraphe 
+manuel de notation est accessible par des liens dans le paragraphe
 @strong{Voir aussi}.
 
 
 @node About the Internals Reference (IR)
 @unnumberedsubsec About the Internals Reference (IR)
 
-@c zzz
-
-@itemize
+@cindex retoucher
+@cindex variables
+@cindex propriétés
+@cindex lilypond-internals
+@cindex documentation du fonctionnement interne
+@cindex Scheme
+@cindex étendre lilypond
+@cindex index
 
-@item
-La
-@iftex
-référence du programme
-@end iftex
-@ifnottex
-@ref{Top,Internals Reference,,lilypond-internals}
-@end ifnottex
-est un ensemble de pages HTML étroitement liées entre elles, qui
-documente les moindres petits détails de chaque classe, objet et
-fonction de LilyPond.  Cette documentation est produite directement à
-partir des définitions de formatage utilisées.
+@ref{Top,Internals Reference,,lilypond-internals,Référence des
+propriétés internes} : c'est un ensemble de pages HTML étroitement
+liées entre elles, qui documente les moindres petits détails de chaque
+classe, objet et fonction de LilyPond.  Cette documentation est
+produite directement à partir des définitions de formatage utilisées.
 
 Presque toutes les fonctions de formatage utilisées en interne sont
 directement disponibles pour l'utilisateur.  Par exemple, toutes les
@@ -1030,41 +1072,47 @@ variables qui contrôlent les épaisseurs, les distances etc., peuvent
 être modifiées dans les fichiers d'entrée.  Il y a un grand nombre
 d'options de formatage, et elles sont toutes décrites dans ce
 document.  Chaque section du manuel de notation a un paragraphe @b{Voir
-aussi} qui renvoie à la documentation générée automatiquement.  Dans la
+aussi}, qui renvoie à la documentation générée automatiquement.  Dans la
 documentation au format HTML, ces paragraphes disposent de liens
 cliquables.
 
-@end itemize
-
 
 @node Other documentation
 @unnumberedsubsec Other documentation
 
-FIXME: most of this should go higher up.  Discuss News, mailist
-archives, ...?
+Pour finir, présentons d'autres précieuses sources de documentation.
 
-There are a number of other places which may be very valuable.
+@itemize
 
-Lorsque vous serez un utilisateur expérimenté, vous pourrez consulter le
-manuel comme une référence : il y a un index complet@footnote{Si vous
-cherchez quelque chose sans le trouver dans la documentation, c'est un
-bogue.  Dans ce cas, merci d'envoyer un rapport de bogue.}, mais le
-manuel est aussi disponible en
-@iftex
-une seule grande page,
-@end iftex
-@ifhtml
-@uref{source/Documentation/user/lilypond-big-page.html, une seule grande
-page},
-@end ifhtml
-ce qui facilite la recherche avec la fonction adéquate de votre
-navigateur.
-
-Dans tous les documents HTML qui incluent des fragments musicaux,
-le code Lilypond utilisé pour produire l'image est accessible par un
-clic sur l'image.
-
-L'emplacement des fichiers de documentation mentionnés ici peut varier
+@item Nouveautés : ce document résume les changements importants et
+les nouvelles fonctionalités de LilyPond depuis la dernière version
+stable.
+
+@item @uref{http://lists.gnu.org/archive/html/lilypond-user/, Les
+archives de la liste lilypond-user} : c'est un dépôt archivant les
+courriels qui ont été envoyés à la liste anglophone des utilisateurs.
+Beaucoup de questions sont apparues plusieurs fois sur la liste, il y
+a donc des chances que si vous avez une question, la réponse puisse
+être dans ces archives.
+@c DIV specific
+@uref{http://lists.gnu.org/archive/html/lilypond-user-fr/,Les archives
+de la liste francophone} ne sont pas aussi bien fournies, mais vous
+pouvez toujours y chercher des conversations passées sur les
+traductions, et si vous avez de la chance une réponse à une question.
+@c END DIV
+
+@item @uref{http://lists.gnu.org/archive/html/lilypond-devel/, Les
+archives de la liste lilypond-devel} : les courriels envoyés à la
+liste des développeurs y sont archivés.  Les sujets de discussion sont
+plus techniques ; si vous voulez vous renseigner sur l'histoire du
+développement ou si vous avez une question très technique, tentez
+votre chance en cherchant dans ces archives.
+
+@item Fragments de musique au cours du texte : dans tous les documents
+HTML qui incluent des fragments musicaux, le code LilyPond utilisé
+pour produire l'image est accessible par un clic sur l'image.
+
+@item L'emplacement des fichiers de documentation mentionnés ici peut varier
 d'un système à l'autre.  De temps en temps, ce manuel fait référence aux
 fichiers d'exemple et d'initialisation.  Tout au long de ce manuel, nous
 donnons les emplacements des fichiers d'entrée relativement au
@@ -1077,16 +1125,4 @@ fichiers d'initialisation, par exemple @file{scm/@/lily@/.scm}, ou
 @file{ly/@/engraver@/-init@/.ly}, se trouvent généralement dans le
 répértoire @file{/usr/@/share/@/lilypond/}.
 
-@cindex retoucher
-@cindex variables
-@cindex propriétés
-@cindex lilypond-internals
-@cindex documentation du fonctionnement interne
-@cindex Scheme
-@cindex étendre lilypond
-@cindex index
-
-Pour finir, ce manuel et les autres sont disponibles en ligne, à la
-fois aux formats PDF et HTML, à partir du site Web, accessible
-à l'adresse @uref{http://@/www@/.lilypond@/.org/}.
-
+@end itemize
diff --git a/Documentation/fr/user/lilypond.tely b/Documentation/fr/user/lilypond.tely
index d6d18eb4ad..9401afdebe 100644
--- a/Documentation/fr/user/lilypond.tely
+++ b/Documentation/fr/user/lilypond.tely
@@ -147,7 +147,7 @@ ligne de ce manuel, ainsi qu'une documentation supplémentaire.
 @menu
 * Musical notation::               notation générale.
 * Specialist notation::            notation à usage spécifique.
-* Input syntax::                   généralités sur les fichiers sources.
+* General input and output::       généralités sur les fichiers sources.
 * Non-musical notation::           aspects autres que la notation musicale.
 * Spacing issues::                 mise en page de la musique sur le papier.
 * Changing defaults::              ajustement de la gravure.
diff --git a/Documentation/fr/user/tutorial.itely b/Documentation/fr/user/tutorial.itely
index 0604b0ba43..131ef7cafc 100644
--- a/Documentation/fr/user/tutorial.itely
+++ b/Documentation/fr/user/tutorial.itely
@@ -1,7 +1,7 @@
 @c -*- coding: utf-8; mode: texinfo; documentlanguage: fr -*-
 @c This file is part of lilypond.tely
 @ignore
-   Translation of GIT committish: 71b67137f76fa4e8aede58299630369f616004d9
+   Translation of GIT committish: 1f529784cd672e34f18e534eccf36280c330e934
 
    When revising a translation, copy the HEAD committish of the
    version that you are working on.  See TRANSLATION for details.
@@ -10,36 +10,27 @@
 @c \version "2.11.51"
 
 @ignore
-Tutorial guidelines:
+Tutorial guidelines:  (different from policy.txt!)
 - 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
+    @lilypond[verbatim,quote]
+  or
+    @lilypond[verbatim,quote,relative=2]
 
+  Don't use any other relative=X commands.
 
+- use "aes" and "ees" instead of "as" and "es".  I know it's not
+  correct Dutch naming, but let's not confuse people with this
+  until we get to the Basic notation chapter.
 
-@c   old info that will probably be removed.
-@c TODO:
-@c   * more details about running lilypond; error messages,
-@c     compiling/viewing (emacs?)
-@c   * where to go from First steps+More basics?
+- Add "Music Glossary: @rglos{foo}" to the *top* of the relevant
+  portions of the tutorial.
 
-@c  wherever possible, do not include index entries here; the
-@c  index should point to stuff in the reference manual.  -gp
+@end ignore
 
-@c Your first LilyPond score in 10 minutes?
 
 @c Translators: Nicolas Grandclaude, Ludovic Sardain, Gauvain Pocentek
 @c Translation checkers: Jean-Charles Malahieude, Valentin Villenave, John Mandereau
 
-
 @node Tutorial
 @chapter Tutorial
 
@@ -48,28 +39,6 @@ par LilyPond, qui vous permettra de faire fonctionner le logiciel pour
 produire une partition.  Après ce premier contact, nous verrons comment
 créer des partitions utilisant une notation musicale courante.
 
-@ifhtml
-Beaucoup de gens apprennent à  utiliser les programmes en les essayant
-et en bidouillant avec.  C'est également possible avec LilyPond.  Si
-vous cliquez sur une image dans la version HTML de ce manuel, vous
-verrez exactement le code LilyPond utilisé pour générer cette image.
-Essayez sur cette image :
-
-@c no verbatim here
-@c KEEP LY
-@lilypond[quote,ragged-right]
-\relative c'' {
-  c-\markup { \bold \huge { Cliquez ici.  } }
-}
-@end lilypond
-
-En copiant et en collant tout le code de l'extrait ly dans un fichier
-test, vous aurez un modèle de base pour faire vos expériences.  Si vous
-apprenez de cette façon, vous aurez probablement envie d'imprimer ou de
-garder un lien vers l'@ruser{Cheat sheet}, tableau qui répertorie les
-commandes usuelles pour une consultation rapide.
-@end ifhtml
-
 @menu
 * First steps::
 * Single staff notation::
@@ -82,22 +51,28 @@ commandes usuelles pour une consultation rapide.
 @node First steps
 @section First steps
 
-Cette section présente sommairement la façon de travailler avec LilyPond.
+Cette section présente les aspects élémentaires de l'utilisation de
+LilyPond.
 
 @menu
 * Compiling a file::
 * Simple notation::
 * Working on text files::
-* How to read the tutorial::
+* How to read the manual::
 @end menu
 
 
 @node Compiling a file
 @subsection Compiling a file
 
-Le premier exemple montre comment débuter avec LilyPond.  Pour créer
-une partition, on écrit un fichier de texte qui décrit la notation
-musicale.  Par exemple, si l'on écrit
+@cindex compilation
+
+Pour créer une partition avec LilyPond, on écrit un fichier texte,
+appelé fichier source, qui décrit la notation musicale. La
+@emph{compilation} de ce fichier source par LilyPond produit un
+fichier graphique imprimable, et si on le désire un fichier MIDI qui
+peut être joué par un séquenceur.  Voici un premier exemple simple de
+fichier source LilyPond.
 
 @example
 @{
@@ -106,7 +81,8 @@ musicale.  Par exemple, si l'on écrit
 @end example
 
 @noindent
-le résultat ressemblera à
+Le compilation de cette partition donnera quelque chose de sembable à
+l'image ci-dessous.
 
 @c  in this case we don't want verbatim
 @lilypond[quote,ragged-right]
@@ -118,53 +94,68 @@ le résultat ressemblera à
 @c DIV specific
 Il est aussi possible d'utiliser les noms de notes français @samp{do
 re mi fa sol la si}, en insérant au début du fichier la ligne
-@samp{\include "italiano.ly"}
+@samp{\include "italiano.ly"}.
 @c END DIV
 
-@emph{Attention :} tout extrait de code LilyPond doit être entouré
-d'une @{paire d'accolades@}.  De plus, pour éviter toute ambiguïté, il
-est préférable d'entourer les accolades par des espaces ou retours à
-la ligne.  Bien que certains exemples de ce manuel ne comportent pas
-d'accolades, ne les oubliez pas dans vos partitions !
+@warning{Tout extrait de code LilyPond doit être entouré d'une
+@strong{@{ paire d'accolades @}}.  De plus, pour éviter toute
+ambiguïté, il est préférable d'entourer les accolades par des espaces
+ou retours à la ligne.  Bien que certains exemples de ce manuel ne
+comportent pas d'accolades, ne les oubliez pas dans vos partitions !
+Pour plus d'informations sur l'affichage des exemples de cette
+documentation, consultez @ref{How to read the manual}.}
+
 
 @cindex casse, prise en compte de
-De plus, LilyPond est sensible à  la casse.  @code{ @{ c d e @} } est
-un code valide ; @code{ @{ C D E @} } produira un message d'erreur.
+@cindex prise en compte de la casse
+@cindex sensibilité à la casse
+De plus, LilyPond est @strong{sensible à la casse} : le code
+@w{@code{@{ c d e @}}} est valide, alors que @w{@code{@{ C D E @}}}
+produira un message d'erreur.
 
-@sp 1
+@smallspace
 
 @subheading Entering music and viewing output
 
+@cindex fichier PDF
+@cindex PDF
+@cindex partition, lire
+@cindex lire la partition
+
 Dans cette section nous expliquerons quelles commandes exécuter et
-comment voir ou imprimer le résultat de LilyPond.
+comment voir ou imprimer le résultat produit par LilyPond.
+
+Notez qu'il existe plusieurs éditeurs de texte disponibles avec un bon
+support de LilyPond ; consultez @rprogram{Text editor support}.
+
+@warning{Le premier démarrage de LilyPond peut prendre une minute ou
+deux, afin de faire la liste des polices du système.  LilyPond démarre
+en principe plus rapidement lors des exécutions suivantes.}
+
 
 @subsubheading MacOS X
 
 Si vous double-cliquez sur @code{LilyPond.app}, un fichier d'exemple
 s'ouvrira.  Sauvegardez-le, par exemple, sous @file{test.ly} sur votre
-bureau, et traitez-le ensuite avec la commande du menu @samp{Compile >
-Typeset File}.  Le fichier PDF résultant sera alors affiché sur votre
-écran.
-
-Notez que le premier démarrage peut prendre une minute ou deux, car
-toutes les polices système doivent être d'abord analysées.
+bureau, puis traitez-le avec la commande de menu @samp{Compile >
+Typeset File}.  Le fichier PDF résultant sera alors affiché à l'écran.
 
 À l'avenir, vous aurez certainement recours aux commandes @qq{Nouveau}
 ou @qq{Ouvrir}.  Vous devez enregistrer votre fichier avant de lancer
-la création de la partition.  Si une erreur advient pendant le
-traitement, vous la trouverez dans la fenêtre @qq{log}.
+la gravure de la partition par LilyPond.  Si une erreur apparaît
+pendant le traitement, vous la trouverez dans la fenêtre @qq{log}.
 
 @subsubheading Windows
 
-Sous Windows, lorsque vous double-cliquez sur l'icône LilyPond qui se
-trouve sur le Bureau, un fichier d'exemple s'ouvre dans un simple
-éditeur de texte.  Enregistrez-le, par exemple en tant que
-@file{test.ly} sur votre Bureau, puis double-cliquez sur son icône
-(qui montre une note de musique) pour le traiter.  Après quelques
-secondes, vous obtiendrez un fichier @file{test.pdf} sur votre Bureau,
-fichier que vous pourrez ouvrir pour voir la partition imprimée.  Une
-autre méthode pour lancer le traitement du fichier @file{test.ly} est
-de le glisser avec votre souris sur l'icône de LilyPond.
+Sous Windows, double-cliquez sur l'icône LilyPond qui se trouve sur le
+bureau, un fichier d'exemple s'ouvre dans un simple éditeur de texte.
+Enregistrez-le, par exemple en tant que @file{test.ly} sur le bureau,
+puis double-cliquez sur son icône (qui montre une note de musique)
+pour le traiter.  Après quelques secondes, vous obtiendrez un fichier
+@file{test.pdf} sur le bureau, fichier que vous pourrez ouvrir pour
+voir la partition gravée.  Une autre méthode pour lancer le traitement
+du fichier @file{test.ly} est de le glisser avec votre souris sur
+l'icône de LilyPond.
 
 Pour modifier un fichier @file{.ly} existant, faites un clic droit
 dessus et sélectionnez @qq{Éditer la source}.  Pour partir d'un
@@ -173,26 +164,12 @@ utilisez la commande @qq{New} du menu @qq{File}.
 
 En double-cliquant sur le fichier, vous obtiendrez, en plus du fichier
 PDF, un fichier @file{.log} qui récapitule les opérations que LilyPond
-a effectuées sur votre fichier.  Si une erreur survient, c'est ce
-fichier qu'il vous faudra étudier.
-
-Notez qu'il existe d'autres éditeurs de texte, certains disposant d'un
-meilleur support pour LilyPond ; reportez-vous à @rprogram{Text editor support}.
-
-@subsubheading Unix
+a effectuées sur votre fichier.  Si une erreur survient, vous en
+trouverez les détails dans ce fichier.
 
+@subsubheading UNIX
 
-Commencez par ouvrir une fenêtre de terminal et un éditeur de
-texte.  Par exemple, vous pouvez ouvrir un xterm et exécuter
-@code{joe}.  @footnote{Il existe des fichiers de macros pour les fans
-de VIM et un
-@code{LilyPond-mode} pour les fans d'Emacs.   S'ils ne sont pas
-encore installés, consultez le fichier @file{INSTALL.txt}.  L'outil
-d'édition le plus facile d'utilisation est de loin
-@file{LilyPondTool}.  Vous trouverez plus d'informations dans
-@rprogram{Text editor support}.}  Dans votre
-éditeur, entrez le texte suivant et sauvegardez le fichier sous
-@file{test.ly}
+Créez un fichier texte @file{test.ly} qui contient
 
 @verbatim
 {
@@ -201,47 +178,41 @@ d'édition le plus facile d'utilisation est de loin
 @end verbatim
 
 @noindent
-Pour traiter @file{test.ly}, procédez comme ceci :
+Pour traiter @file{test.ly}, entrez la commande suivante dans un
+terminal :
 
 @example
 lilypond test.ly
 @end example
 
 @noindent
-Vous verrez quelque chose ressemblant à  :
+Vous verrez quelque chose ressemblant à
 
 @example
 lilypond test.ly
-GNU LilyPond 2.10.0
-Processing `test.ly'
-Parsing...
-Interpreting music...  [1]
-Preprocessing graphical objects...
-Calculating line breaks...  [2]
-Layout output to `test.ps'...
-Converting to `test.pdf'...
+GNU LilyPond @version{}
+Traitement de « test.ly »
+Analyse...
+Interprétation en cours de la musique...
+Pré-traitement des éléments graphiques...
+Détermination du nombre optimal de pages...
+Répartition de la musique sur une page...
+Dessin des systèmes...
+Sortie mise en page vers « test.ps »...
+Conversion à « ./test.pdf »...
 @end example
 
 @c DIV specific
-Suivant votre installation, ces messages peuvent être traduits.
-@c END DIV
-
-@cindex fichier PDF
-@cindex visionnage de la musique
-
 @noindent
-De tout cela résulte un fichier @file{test.pdf}, que vous pouvez imprimer
-ou visualiser avec les outils standards de votre système
-d'exploitation.  @footnote{Si votre système ne dispose pas des outils
-nécessaires, vous pouvez essayer
-@uref{http://@/www@/.cs@/.wisc@/.edu/@/~ghost/,Ghostscript}, un
-programme pour afficher et imprimer librement les fichiers PDF et PostScript.}
+Suivant votre installation, ces messages peuvent être traduits ou
+non.
+@c END DIV
 
 
 @node Simple notation
 @subsection Simple notation
 
-Il y a certains éléments graphiques que LilyPond ajoute
+Il y a certains éléments graphiques de notation que LilyPond ajoute
 automatiquement.  Dans l'exemple suivant, nous n'avons fourni que
 quatre hauteurs, mais LilyPond a ajouté une clé, un chiffre de mesure
 et du rythme.
@@ -253,29 +224,38 @@ et du rythme.
 @end lilypond
 
 @noindent
-Ce comportement peut être modifié, mais dans bien des cas ces
-attributions automatiques s'avèrent utiles.
+Ces valeurs automatiques simplifient la saisie du code source dans
+bien des cas ; nous verrons plus loin comment les indiquer
+explicitement.
 
 
-@subheading Pitches
+@subheading Hauteurs
+
+Glossaire musical : @rglos{pitch}, @rglos{interval},
+@rglos{scale}, @rglos{middle C}, @rglos{octave},
+@rglos{accidental}.
+
 Le moyen le plus simple d'entrer des notes est d'utiliser le mode
-@code{\relative}.  Avec ce mode, l'@rglos{interval} entre la note et
-celle qui la précède est supposé inférieur ou égal à une
-@rglos{fourth}.  Commençons par entrer la partition la plus
-élémentaire qui soit, une @rglos{scale}.
+d'octaves relatives, ou mode @code{\relative}.  Dans ce mode, l'octave
+de chaque note est sélectionnée automatiquement de façon à ce qu'elle
+soit la plus proche possible de la note précédente, c'est-à-dire de
+façon à ce que l'intervalle avec la note précédente soit au plus d'une
+quarte.  Commençons par saisir une partition très simple, à savoir une
+gamme.
 
 @lilypond[quote,ragged-right,verbatim]
-\relative c' {
+\relative c' {  % set the starting point to middle C
   c d e f
   g a b c
 }
 @end lilypond
 
-La note de départ est @rglos{middle C}.  Chacune des notes qui suivent
-est à moins d'une quarte de la note précédente --- en d'autres termes,
-le premier @samp{c} est le do central, entre la clé de sol et
-la clé de fa, puis est suivi par le ré le plus proche, et ainsi de
-suite.  On peut bien sûr créer des mélodies d'intervalles plus étendus :
+La note de départ est le @notation{do central}.  Chacune des notes qui
+suivent est placée à l'octave la plus proche de la note précédente ---
+en d'autres termes, le premier @samp{c} est le do central, entre la
+clé de sol et la clé de fa, puis est suivi par le ré le plus proche,
+et ainsi de suite.  On peut bien sûr créer des mélodies avec de plus
+grands intervalles, toujours avec le mode @code{\relative} :
 
 @lilypond[quote,ragged-right,verbatim]
 \relative c' {
@@ -285,14 +265,48 @@ suite.  On peut bien sûr créer des mélodies d'intervalles plus étendus :
 @end lilypond
 
 @noindent
-Comme vous l'aurez remarqué, cet exemple ne commence plus sur le do du
-milieu.  La première note --- le @samp{d} --- est le ré qui en est le
-plus proche.
+Remarquez que cet exemple ne commence plus sur le do central : la
+première note --- le @samp{d} --- est le ré qui en est le plus proche.
+
+Dans l'exemple suivant, on remplace @code{c'} dans la commande
+@w{@code{\relative c'}} par @code{c''}, afin de calculer l'octave de
+la première note par rapport au do situé une octave au-dessus du do
+central :
+
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {  % one octave above middle C
+  e c a c
+}
+@end lilypond
+
+Le mode d'octaves relatives peut être déroutant au début, mais c'est
+souvent la façon la plus économique de saisir les hauteurs en
+utilisant le clavier de l'ordinateur de façon classique.  Détaillons
+sur un exemple le calcul des octaves relatives.  En partant d'un si
+sur la troisième ligne de la clé de sol, un do, un ré ou un mi sans
+indication d'octave particulière seront placés juste au-dessus du si,
+c'est-à-dire au plus à une quarte ascendante du si, alors qu'un la, un
+sol ou un fa seront placés juste en-dessous du si, c'est-à-dire au
+plus à une quarte descendante du si.
+
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+  b c  % c is 1 staff space up, so is the c above
+  b d  % d is 2 up or 5 down, so is the d above
+  b e  % e is 3 up or 4 down, so is the e above
+  b a  % a is 6 up or 1 down, so is the a below
+  b g  % g is 5 up or 2 down, so is the g below
+  b f  % f is 4 up or 3 down, so is the f below
+}
+@end lilypond
 
-Pour ajouter des intervalles supérieurs à une quarte, il suffit
-d'indiquer si la note est à l'octave supérieure ou inférieure, en
-ajoutant respectivement une apostrophe @code{'} ou une virgule
-@code{,} au nom de la note.
+Notez que le calcul des octaves relatives @strong{ne dépend pas des
+altérations} des notes, dièses bémols ou bécarre.
+
+Pour obtenir des intervalles supérieurs à une quarte, on peut ajouter
+des apostrophes @code{'} --- qui font chacune monter la hauteur d'une
+octave --- ou des virgules @code{,} --- qui font chacune descendre la
+hauteur d'une octave --- au nom de la note.
 
 @lilypond[quote,ragged-right,verbatim]
 \relative c'' {
@@ -303,21 +317,29 @@ ajoutant respectivement une apostrophe @code{'} ou une virgule
 
 @noindent
 Pour déplacer une note deux octaves (ou davantage !) plus haut ou plus
-bas, il suffit de mettre plusieurs @code{''} ou plusieurs @code{,,} ---
+bas, il suffit de mettre deux (ou davantage) de @code{'} ou ou @code{,} ---
 attention cependant à bien mettre deux apostrophes @code{''}, et non
 un guillemet @code{"}@tie{}!  C'est de cette même manière que l'on
 peut modifier la valeur de départ de @code{\relative c'}.
 
 
-@subheading Durations (rhythms)
+@subheading Durées et rythme
 
-La @rglos{duration} d'une note est indiquée par un nombre
-qui suit son nom : @samp{1} pour une @rglos{whole
-note}, @samp{2} pour une @rglos{half note}, @samp{4} pour
-une @rglos{quarter note} et ainsi de suite.  Les hampes sont
-ajoutées automatiquement.
+Glossaire musical : @rglos{beam}, @rglos{duration},
+@rglos{whole note}, @rglos{half note}, @rglos{quarter note},
+@rglos{dotted note}.
 
-@lilypond[quote,ragged-right,verbatim]
+La @notation{durée} d'une note est indiquée par un nombre qui suit sa
+hauteur : @samp{1} pour une @notation{ronde}, @samp{2} pour une
+@notation{blanche}, @samp{4} pour une @notation{noire} et ainsi de
+suite.  Les @notation{crochets} et @notation{liens} sont ajoutées
+automatiquement.
+
+Si aucune durée n'est indiquée pour une note, la dernière durée entrée
+est utilisée.  En l'absence d'indication de durée, la première note
+est une noire.
+
+@lilypond[verbatim,quote,ragged-right]
 \relative c'' {
   a1
   a2 a4 a8 a
@@ -325,15 +347,10 @@ ajoutées automatiquement.
 }
 @end lilypond
 
-@noindent
-Si aucune durée n'est indiquée, la dernière durée entrée sera utilisée
-pour les notes suivantes.  En l'absence d'indication, la première note
-est une noire.
-
-Une @rglos{dotted note} s'obtient en ajoutant un point @samp{.}  à
-la valeur rythmique.
+Une @notation{note pointée} s'obtient en ajoutant un point @code{.}  à
+la valeur rythmique.  Le point doit être précédé d'un nombre de durée.
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right]
 \relative c'' {
   a a a4. a8
   a8. a16 a a8. a8 a4.
@@ -341,12 +358,14 @@ la valeur rythmique.
 @end lilypond
 
 
-@subheading Rests
+@subheading Silences
 
-On saisit un @rglos{rest} tout comme une note, mais avec le
-caractère @samp{r}.
+Glossaire musical : @rglos{rest}.
 
-@lilypond[quote,ragged-right,verbatim]
+On saisit un @notation{silence} tout comme une note, mais avec la
+lettre @samp{r}.
+
+@lilypond[verbatim,quote,ragged-right]
 \relative c'' {
   a r r2
   r8 a r4 r4. r8
@@ -354,12 +373,14 @@ caractère @samp{r}.
 @end lilypond
 
 
-@subheading Time signature
+@subheading Métrique
 
-La @rglos{time signature} peut être définie à l'aide de la commande
-@code{\time} :
+Glossaire musical : @rglos{time signature}.
 
-@lilypond[quote,ragged-right,verbatim]
+La @notation{métrique}, aussi appelée @notation{chiffre de mesure},
+peut être définie à l'aide de la commande @code{\time} :
+
+@lilypond[verbatim,quote,ragged-right]
 \relative c'' {
   \time 3/4
   a4 a a
@@ -373,9 +394,12 @@ La @rglos{time signature} peut être définie à l'aide de la commande
 
 @subheading Clef
 
-La @rglos{clef} peut être définie à l'aide de la commande @code{\clef} :
+Glossaire musical : @rglos{clef}.
 
-@lilypond[quote,ragged-right,verbatim]
+La @notation{clef} peut être définie à l'aide de la commande
+@code{\clef} :
+
+@lilypond[verbatim,quote,ragged-right]
 \relative c' {
   \clef treble
   c1
@@ -389,11 +413,12 @@ La @rglos{clef} peut être définie à l'aide de la commande @code{\clef} :
 @end lilypond
 
 
-@subheading All together
+@subheading Tout ensemble
 
-Voici un bref exemple qui montre tous ces éléments ensemble :
+Voici un bref exemple qui rassemble tous les éléments que nous déjà
+vus :
 
-@lilypond[quote,ragged-right,verbatim]
+@lilypond[verbatim,quote,ragged-right]
 \relative c, {
   \time 3/4
   \clef bass
@@ -403,35 +428,29 @@ Voici un bref exemple qui montre tous ces éléments ensemble :
 @end lilypond
 
 @seealso
-@quotation
-@table @asis
-@item Entrer des hauteurs et des durées
-voir @ruser{Pitches} and @ruser{Durations}.
-@item Les silences
-voir @ruser{Rests}.
-@item Les chiffres de mesure et autres commandes de métrique
-voir @ruser{Time signature}.
-@item Les clés
-voir @ruser{Clef}.
-@end table
-@end quotation
+
+Manuel de notation : @ruser{Writing pitches},
+@ruser{Writing rhythms}, @ruser{Writing rests},
+@ruser{Time signature}, @ruser{Clef}.
 
 
 @node Working on text files
 @subsection Working on text files
 
 Le traitement des fichiers source de LilyPond est semblable à celui du
-code de nombreux langages de programmation répandus : la casse est prise
+code de nombreux langages de programmation.  La casse est prise
 en compte, et les caractères considérés comme espaces ont généralement
 peu d'importance.  Les expressions sont délimitées par des accolades @{
 @}, et les commentaires par @code{%} ou @code{%@{ ... %@}}.
 
 Si cette phrase vous paraît incompréhensible, ne vous en faites pas !
-Tous ces termes vont être expliqués :
+Expliquons tous ces termes :
 
 @itemize
 
 @cindex casse, prise en compte de
+@cindex prise en compte de la casse
+@cindex sensibilité à la casse
 @item @strong{La casse} :
 LilyPond est sensible à la casse, c'est à dire qu'une lettre capitale
 n'a pas la même valeur qu'une lettre minuscule.  Les notes, par
@@ -450,9 +469,10 @@ c                        d
 @end example
 
 @noindent
-Bien sûr, ce dernier exemple est difficile à lire.  Une bonne habitude
+Bien sûr, ce dernier exemple est illisible.  Une bonne habitude
 à prendre est d'indenter les blocs de code avec soit des tabulations
 soit des doubles espaces :
+
 @example
 @{
   c d e
@@ -462,30 +482,42 @@ soit des doubles espaces :
 @item @strong{Expressions musicales} :
 Tout morceau saisi dans LilyPond doit être placé entre @strong{@{
 accolades @}}.  Ces caractères indiquent à LilyPond que ce bloc de
-texte est une et une seule expression musicale, tout comme les
-parenthèses @samp{()} en mathématiques.  Il est préférable, pour
-éviter toute ambiguïté, d'entourer tous ces crochets d'espaces, à
-moins qu'ils se trouvent au début ou à la fin d'une ligne.
+texte représente une et une seule expression musicale, tout comme les
+parenthèses @samp{()} en mathématiques.  Pour éviter toute ambiguïté,
+il est préférable d'entourer ces accolades d'espaces ou de retours à
+la ligne.
 
-Une fonction --- @code{\relative @{ @}} par exemple --- compte
-également comme une seule expression musicale.
+Un appel de fonction --- @w{@code{\relative @{ @}}} par exemple ---
+compte également comme une seule expression musicale.
 
-@cindex commentaires
+@cindex commentaire
 @cindex commentaire de fin de ligne
 @cindex commentaire-bloc
+@cindex bloc de commentaire
 @item @strong{Les commentaires} :
-Un commentaire est une indication pour tout lecteur humain d'un
-fichier de musique ; il est ignoré par l'ordinateur, et n'a donc aucun
-effet sur la partition imprimée.  On distingue deux types de
-commentaires :
-@itemize @bullet
-@item la ligne de commentaire, introduite par le symbole @samp{%} :
-tout ce qui suit ce symbole sur cette ligne sera ignoré.
-@item le bloc de commentaire, qui peut être de plusieurs lignes voire
-de toute une section : tout ce qui se trouve entre @code{%@{} et
-@code{%@}} est ignoré.  Les blocs de commentaires ne peuvent s'imbriquer.
-@end itemize
-Le fragment suivant met en évidence quelques usages possibles des commentaires :
+un commentaire est une indication pour tout lecteur humain d'un
+fichier source de musique ; il est ignoré par l'ordinateur, et n'a
+donc aucun effet sur la partition imprimée.  On distingue deux types
+de commentaires.  Le commentaire de fin de ligne, introduit par le
+symbole @samp{%} : tout ce qui suit ce symbole sur la même ligne sera
+ignoré.  Par convention, un commentaire qui occupe une ligne entière
+se place juste @emph{au-dessus} de la ligne à laquelle il fait
+référence.
+
+@example
+a4 a a a
+% ce commentaire fait référence aux sis
+b2 b
+@end example
+
+Le bloc de commentaire, qui peut occuper plusieurs lignes voire toute
+une section : tout ce qui se trouve entre @code{%@{} et @code{%@}} est
+ignoré.  Les blocs de commentaires ne peuvent s'imbriquer, ce qui
+signifie que vous ne pouvez pas placer un commentaire-bloc à
+l'intérieur d'un autre commentaire-bloc.  Si jamais vous essayez, vous
+verrez que la première occurence de @code{%@}} terminera @qq{les
+@emph{deux} commentaires-blocs}.  Le fragment suivant met en évidence
+quelques usages possibles des commentaires :
 
 @example
 % voici les notes de "ah vous dirai-je maman"
@@ -496,128 +528,132 @@ Le fragment suivant met en évidence quelques usages possibles des commentaires
    seront ignorées, car elles se trouvent
    dans un bloc de commentaire.
 
-   g g f f e e d d c2
+   f f e e d d c2
 %@}
 @end example
 
 @end itemize
 
-Vous trouverez plus d'astuces pour organiser vos fichiers LilyPond dans
-@ref{Suggestions for writing LilyPond files}.
 
 
-@node How to read the tutorial
-@subsection How to read the tutorial
+@node How to read the manual
+@subsection How to read the manual
 
 Comme nous l'avons vu dans @ref{Working on text files}, un code
-LilyPond doit être encadré par des @{ @} ou bien par @code{\relative
-c'' @{ ...  @}} afin d'être compris.  Cependant, dans la suite de ce
+LilyPond doit être encadré par des accolades @{ @} ou bien par
+@code{\relative c'' @{ ...  @}}.  Cependant, dans la suite de ce
 manuel, la plupart des exemples ne feront pas apparaître ces signes.
 
-Si vous consultez la documentation au format HTML, et que vous
-souhaitez voir la source exacte d'un exemple, il vous suffit de
-cliquer sur l'image.  Si vous ne disposez pas de la version HTML, il
-vous est possible de simplement copier et coller le code affiché, mais
-@strong{à condition} d'ajouter @code{\relative c'' @{ @}} de la façon
-suivante :
+Pour reproduire les exemples, vous pouvez copier et coller le code
+affiché, mais @strong{à condition} d'ajouter @code{\relative c'' @{
+@}} de la façon suivante :
 
 @example
 \relative c'' @{
- ...  collez ici votre exemple...
+  ...collez ici votre exemple...
 @}
 @end example
 
-Pourquoi avoir omis les accolades ? La plupart des exemples de ce
+Pourquoi avoir omis les accolades ?  La plupart des exemples de ce
 manuel peuvent être insérés au milieu d'un morceau de musique plus
 long.  Il n'y a donc aucune raison d'ajouter @code{\relative c'' @{
-@}} à ces exemples --- en effet, il n'est pas possible d'insérer un
-@code{\relative} à l'intérieur d'un autre @code{\relative}.  Il vous
-serait donc devenu impossible de copier un bref exemple de la
-documentation et de le coller dans une pièce de votre cru.
+@}} à ces exemples --- en effet, il n'est pas possible d'insérer une
+expression @code{\relative} à l'intérieur d'un autre expression
+@code{\relative}.  Si nous mettions tous nos exemples dans une
+expression @code{\relative}, vous ne pourriez plus copier un bref
+exemple de la documentation pour le coller dans vos pièces.
+
+
+@subheading Exemples cliquables
+
+Beaucoup de gens apprennent à  utiliser les programmes en les essayant
+et en bidouillant avec.  C'est également possible avec LilyPond.  Si
+vous cliquez sur une image dans la version HTML de ce manuel, vous
+verrez exactement le code LilyPond utilisé pour générer cette image.
+Essayez sur cette image :
+
+@c no verbatim here
+@c KEEP LY
+@lilypond[quote,ragged-right]
+\relative c'' {
+  c-\markup { \bold \huge { Cliquez ici.  } }
+}
+@end lilypond
+
+En copiant-collant le code à partir du commentaire @qq{ly snippet}
+vers un fichier test, vous aurez un modèle de base pour faire vos
+expériences.  Pour obtenir une gravure à l'identique, copiez tout le
+code à partir de @qq{Start cut-&-pastable section}.
+
+@c No longer in the text in English, but should we really
+@c remove this? --jm
+@ignore
+Si vous apprenez de cette façon, vous aurez probablement envie
+d'imprimer ou de garder un lien vers @ruser{Cheat sheet}, tableau
+qui répertorie les commandes usuelles pour une consultation rapide.
+@end ignore
+
+@seealso
+
+Vous trouverez plus de conseils pour construire des fichiers source
+dans @ref{Suggestions for writing LilyPond input files}.  Cependant,
+lors d'une première lecture il est préférable de terminer d'abord la
+lecture du tutoriel.
+
 
 @node Single staff notation
 @section Single staff notation
 
 Cette section présente la notation courante dont on a besoin pour
-écrire une seule voix sur une seule portée.
+écrire une voix sur une portée.
 
 @menu
-* Relative note names::
 * Accidentals and key signatures::
 * Ties and slurs::
 * Articulation and dynamics::
+* Adding text::
 * Automatic and manual beams::
 * Advanced rhythmic commands::
 @end menu
 
 
-@node Relative note names
-@subsection Relative note names
-
-Comme nous l'avons vu dans @ref{Simple notation}, LilyPond calcule la
-hauteur de chaque note en fonction de la précédente@footnote{Il existe
-un autre mode de saisie des hauteurs, le mode @ref{Absolute note
-names}, mais en pratique il est bien plus aisé et sûr d'avoir recours
-au mode de hauteurs relatives.}.  Si aucune indication supplémentaire
-d'octaviation n'est ajoutée, il en concluera que chaque hauteur est
-située à une quarte au plus de la note précédente.
-
-Lilypond tient compte des intervalles induits par les noms des notes
---- en d'autres termes, une quarte augmentée n'est @emph{pas}
-équivalente à une quinte diminuée.  Ainsi, si l'on part d'un Do, un Fa
-dièse sera placé au-dessus, tandis qu'un Sol bémol sera placé
-au-dessous.
-
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
-c2 fis
-c2 ges
-@end lilypond
-
-@seealso
-@quotation
-@table @asis
-@item Les hauteurs de note relatives
-voir @ruser{Relative octaves}.
-@item Les vérifications d'octaves
-voir @ruser{Octave check}.
-@end table
-@end quotation
-
-
-
 @node Accidentals and key signatures
 @subsection Accidentals and key signatures
 
 @subheading Accidentals
 
-Dans la notation par défaut, un @rglos{sharp} s'obtient en ajoutant
-@samp{is} au nom de la note, et un @rglos{flat} en ajoutant @samp{es}.
-Comme vous pouvez vous y attendre, un double dièse ou double bémol est
-alors obtenu en ajoutant @samp{isis} ou @samp{eses}@footnote{Cette
-syntaxe est dérivée de la convention de dénomination des notes dans
-les langues nordiques et germaniques, comme l'allemand ou le
-hollandais.}.
+Glossaire musical : @rglos{sharp}, @rglos{flat}, @rglos{double sharp},
+@rglos{double flat}, @rglos{accidental}.
+
+Dans la notation par défaut, on obtient un @notation{dièse} en
+ajoutant @code{is} au nom de la note, et un @notation{bémol} en
+ajoutant @code{es}.  Comme vous pouvez vous y attendre, un double
+dièse ou double bémol s'obtiennent en ajoutant @code{isis} ou
+@code{eses}.  Cette syntaxe est dérivée de la convention de
+dénomination des notes dans les langues nordiques et germaniques,
+comme l'allemand ou le hollandais.
 
 @c DIV specific
-Cependant, si vous utilisez la commande @samp{\include "italiano.ly"}
+Cependant, si vous utilisez la commande @code{\include "italiano.ly"}
 pour entrer les noms de notes français au lieu des noms hollandais, il
-faudra ajouter un @samp{d} pour un dièse, et un @samp{b} pour un
-bémol.  Le double dièse et le double bémol s'obtiennent en ajoutant
-respectivement @samp{dd} et @samp{bb}
+faudra ajouter un @code{d} pour obtenir un dièse, et un @code{b} pour
+un bémol.  Le double dièse et le double bémol s'obtiennent en ajoutant
+respectivement @code{dd} et @code{bb}.  Pour en savoir plus sur les
+autres langues disponibles, consultez @ruser{Note names in other
+languages}.
 @c END DIV
 
-Pour en savoir plus sur les autres langues disponibles, voir @ruser{Note
-names in other languages}.
-
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 cis1 ees fisis, aeses
 @end lilypond
 
-@cindex armure, définition de
+@cindex armure, définition de l'
+@cindex armure, altérations à l'
+@cindex altérations à l'armure
 @subheading Key signatures
 
 L'armure est déterminée par la commande @code{\key}, suivie d'une
-hauteur puis de @code{\major} (majeur) ou @code{\minor} (mineur) :
+hauteur puis de @code{\major} (majeur) ou @code{\minor} (mineur).
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \key d \major
@@ -626,28 +662,32 @@ a1
 a
 @end lilypond
 
-@sp 1
+@smallspace
 
 @subheading Warning: key signatures and pitches
 
-La combinaison de l'armure et des hauteurs de note --- y compris les
-altérations --- permet à LilyPond de déterminer dans quel cas afficher
-les altérations accidentelles.  L'armure n'affecte que les altérations
-@emph{imprimées}, et non les hauteurs réelles ! Cette fonctionnalité
-est souvent source de confusion pour les nouveaux utilisateurs, aussi
-expliquons-la en détail.
-
-LilyPond fait une nette distinction entre le contenu musical et la
-mise en forme.  L'altération d'une note --- bémol, bécarre ou dièse
---- fait partie de sa hauteur, et relève donc du contenu musical.  La
-présence ou non d'une altération accidentelle --- un @emph{signe}
-bémol, bécarre ou dièse --- devant la note correspondante est une
-question qui relève de la mise en page.  Mettre en page une partition
-se fait selon des règles ; les altérations accidentelles seront donc
-automatiquement imprimées suivant ces règles.  Les hauteurs de note,
-en revanche, relèvent de ce que vous voulez entendre ; et, dans la
-mesure où la musique que vous entrez est censée être celle que vous
-voulez entendre, LilyPond (qui n'est chargé que de la gravure) ne les
+Glossaire musical : @rglos{accidental}, @rglos{key signature},
+@rglos{pitch}, @rglos{flat}, @rglos{natural}, @rglos{sharp},
+@rglos{transposition}.
+
+La combinaison de l'@notation{armure} et des hauteurs de note --- y
+compris les altérations --- permet à LilyPond de déterminer dans quel
+cas imprimer des @notation{altérations accidentelles}.  L'armure
+n'affecte que les altérations @emph{imprimées}, et non les hauteurs
+réelles ! Cette fonctionnalité est souvent source de confusion pour
+les nouveaux utilisateurs, aussi expliquons-la en détail.
+
+LilyPond fait une distinction nette entre le contenu musical et la
+mise en forme.  L'altération d'une note --- @notation{bémol},
+@notation{bécarre} ou @notation{dièse} --- fait partie de sa hauteur,
+et relève donc du contenu musical.  La gravure ou non d'une altération
+accidentelle --- un @emph{signe} bémol, bécarre ou dièse --- devant la
+note correspondante est une question qui relève de la mise en forme.
+La gravure une partition suit des règles, en particulier des règles
+d'indication des altérations accidentelles.  Les hauteurs de note, en
+revanche, relèvent de ce que vous voulez entendre ; et, dans la mesure
+où la musique que vous entrez est censée être celle que vous voulez
+entendre, LilyPond, qui n'est chargé que de la gravure, ne les
 choisira pas à votre place.
 
 Dans cet exemple,
@@ -659,66 +699,75 @@ d cis fis
 
 @noindent
 aucune note n'a d'altération accidentelle, et pourtant vous devrez
-entrer le @samp{is} pour les notes @code{cis} et @code{fis}.
+entrer le @code{is} pour les notes @code{cis} et @code{fis}.
 
-Le code @samp{e} ne veut pas dire @qq{Imprimez-moi un point noir sur
+Le code @code{e} ne veut pas dire @qq{Imprimez-moi un point noir sur
 la première ligne de la portée.}  Cela signifie plutôt : @qq{Ici se
-trouve une note dont la hauteur est un mi naturel.}  Avec l'armure de
-la bémol majeur, ce mi sera flanqué d'un bécarre accidentel :
+trouve une note dont la hauteur est un mi naturel.}  Avec une armure
+de la bémol majeur, ce mi est flanqué d'un bécarre accidentel :
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \key aes \major
 e
 @end lilypond
 
-Ajouter explicitement toutes les altérations requiert un peu plus
-d'effort dans la phase de saisie, mais la transposition en sera
-grandement facilitée.  De plus les altérations accidentelles peuvent
-être imprimées suivant plusieurs conventions.  Regardez
-@ruser{Automatic accidentals} pour connaître les différentes manières
-dont les altérations accidentelles peuvent être imprimées, suivant les
-règles que vous choisirez.
+Ajouter explicitement toutes les altérations demande un peu plus
+d'effort dans la phase de saisie, mais cela facilite grandement la
+@notation{transposition}.  De plus, les altérations accidentelles
+peuvent ainsi être imprimées suivant plusieurs conventions.  Pour
+connaître les différentes manières dont les altérations accidentelles
+peuvent être imprimées, consultez @ruser{Automatic accidentals}.
 
 @seealso
-@quotation
-@table @asis
-@item Les altérations
-voir @ruser{Accidentals} and @ruser{Automatic accidentals}.
-@item Les armures
-voir @ruser{Key signature}.
-@end table
-@end quotation
 
+Manuel de notation : @ruser{Note names in other languages},
+@ruser{Accidentals}, @ruser{Automatic accidentals},
+@ruser{Key signature}.
+
+Glossaire musical : @rglos{Pitch names}.
 
 @node Ties and slurs
 @subsection Ties and slurs
 
 @cindex liaisons de prolongation
+@cindex liaisons de tenue
+@cindex prolongation, liaisons de
+@cindex durée, liaisons de
+@cindex tenue, liaisons de
 @subheading Ties
-Une @rglos{tie}@footnote{parfois aussi appelée liaison de
-tenue} se crée en ajoutant un tilde @samp{~} à la première note liée.
 
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+Glossaire musical : @rglos{tie}.
+
+Pour créer une liaison de prolongation@footnote{parfois aussi appelée
+liaison de tenue}, on ajoute un tilde @code{~} à la première note
+liée.
+
+@lilypond[verbatim,quote,relative=2]
 g4~ g c2~
 c4 ~ c8 a8 ~ a2
 @end lilypond
 
 @cindex liaisons d'articulation
+@cindex articulation, liaisons d'
 @subheading Slurs
 
 @c Le terme de "slur" a deux sens en français : articulation et phrasé.
 @c Je garde ici le terme "legato", tel qu'il apparaît dans le texte original,
 @c car c'est celui qui me semble le plus couramment employé.
 
-Une @rglos{slur} d'articulation (ou @qq{legato}) peut englober
-plusieurs notes.  Les notes de départ et d'arrivée reçoivent
-respectivement un signe @samp{(} et @samp{)}.
+Glossaire musical : @rglos{slur}.
 
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+Une liaison d'articulation ou @emph{legato} peut englober
+plusieurs notes.  Les notes de départ et d'arrivée sont suivies
+respectivement d'un signe @samp{(} et @samp{)}.
+
+@lilypond[verbatim,quote,relative=2]
 d4( c16) cis( d e c cis d) e( d4)
 @end lilypond
 
 @cindex liaisons de phrasé
+@cindex phrasé, liaisons de
+@cindex legato
 @subheading Phrasing slurs
 
 De plus longues liaisons, dites de phrasé, sont délimitées par @code{\(} et
@@ -729,30 +778,28 @@ phrasés, mais pas plusieurs liaisons de phrasé ou de legato à la fois.
 a8(\( ais b c) cis2 b'2 a4 cis,\)
 @end lilypond
 
-@sp 1
+@smallspace
 
-@cindex liaisons de phrasé et de prolongation, différences
+@cindex liaisons d'articulation et de prolongation, différences
 @subheading Warnings: slurs vs. ties
 
+Glossaire musical : @rglos{articulation}, @rglos{slur}, @rglos{tie}.
+
 Une liaison d'articulation ou de phrasé ressemble à une liaison de
-tenue, mais n'a pas la même signification.  Alors qu'une liaison de
-tenue ne peut relier que deux notes de même hauteur, le legato indique
-une articulation de plusieurs notes, éventuellement nombreuses.  Les
-liaisons de tenue peuvent être enchâssées dans un legato ou un phrasé.
+prolongation, mais n'a pas la même signification.  Alors qu'une
+liaison de prolongation ne peut relier que deux notes de même hauteur,
+le legato indique une articulation de plusieurs notes, éventuellement
+en grand nombre.  Les liaisons de tenue peuvent être enchâssées dans
+un legato ou un phrasé.
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 c2~( c8 fis fis4 ~ fis2 g2)
 @end lilypond
 
 @seealso
-@quotation
-@table @asis
-@item @ruser{Ties},
-@item @ruser{Slurs},
-@item @ruser{Phrasing slurs}.
-@end table
-@end quotation
 
+Manuel de notation : @ruser{Ties}, @ruser{Slurs},
+@ruser{Phrasing slurs}.
 
 @node Articulation and dynamics
 @subsection Articulation and dynamics
@@ -762,8 +809,10 @@ c2~( c8 fis fis4 ~ fis2 g2)
 @cindex staccato
 @subheading Articulations
 
-Des @rglos{articulation}s peuvent être ajoutées à une note, au moyen
-d'un tiret @samp{-} suivi d'un caractère :
+Glossaire musical : @rglos{articulation}.
+
+Des @notation{articulations} peuvent être ajoutées à une note, au moyen
+d'un tiret @code{-} suivi d'un caractère :
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 c-. c-- c-> c-^ c-+ c-_
@@ -771,6 +820,9 @@ c-. c-- c-> c-^ c-+ c-_
 
 @cindex doigtés
 @subheading Fingerings
+
+Glossaire musical : @rglos{fingering}.
+
 De même, des indications de doigté peuvent être ajoutées à une note en
 utilisant un tiret (@samp{-}) et le chiffre à écrire :
 
@@ -779,10 +831,10 @@ c-3 e-5 b-2 a-1
 @end lilypond
 
 Articulations et doigtés sont habituellement placés automatiquement,
-mais vous pouvez spécifier une direction en utilisant @samp{^} (en haut)
-ou @samp{_} (en bas).  Vous pouvez aussi utiliser plusieurs
-articulations sur la même note.  Dans la plupart des cas, cependant, il
-est mieux de laisser LilyPond déterminer l'emplacement de
+mais vous pouvez indiquer une direction en utilisant @samp{^} (en
+haut) ou @samp{_} (en bas).  Vous pouvez aussi utiliser plusieurs
+articulations sur la même note.  Dans la plupart des cas, cependant,
+il est bon de laisser LilyPond déterminer l'emplacement de
 l'articulation.
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
@@ -790,8 +842,12 @@ c_-^1 d^. f^4_2-> e^-_+
 @end lilypond
 
 @subheading Dynamics
-Les signes de nuances sont obtenus en ajoutant à la note les noms des nuances,
-précédées d'un anti-slash @samp{\} :
+
+Glossaire musical : @rglos{dynamics}, @rglos{crescendo},
+@rglos{decrescendo}.
+
+On obtient un signe de @notation{nuance} en ajoutant à la note les
+lettres du signe, précédées d'un anti-slash @samp{\} :
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 c\ff c\mf c\p c\pp
@@ -804,29 +860,52 @@ c\ff c\mf c\p c\pp
 @c Pluriel des termes musicaux italiens :
 @c selon Littré, plutôt à la française (en "-os" qu'en "-i")
 
-Crescendos et decrescendos débutent avec les commandes @code{\<} et
-@code{\>}.  Ils se terminent soit par une nuance d'arrivée, par exemple
-@code{\f}, soit par la commande @code{\!} :
+@notation{Crescendos} et @notation{decrescendos} débutent avec les
+commandes @code{\<} et @code{\>}.  Ils se terminent soit par une
+nuance d'arrivée, par exemple @code{\f}, soit par la commande
+@code{\!} :
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 c2\< c2\ff\> c2 c2\!
 @end lilypond
 
 @seealso
-@quotation
-@table @asis
-@item @ruser{Articulations}.
-@item @ruser{Fingering instructions}.
-@item @ruser{Dynamics}.
-@end table
-@end quotation
+
+Manuel de notation : @ruser{Articulations and ornamentations},
+@ruser{Fingering instructions}, @ruser{Dynamics}.
+
+
+@node Adding text
+@subsection Adding text
+
+On peut ajouter du texte à une partition :
+
+@lilypond[verbatim,quote,relative=2]
+c1^"espr" a_"legato"
+@end lilypond
+
+Pour mettre en forme du texte, on utilise la commande @code{markup} :
+
+@lilypond[verbatim,quote,relative=2]
+c1^\markup{ \bold espr}
+a1_\markup{
+  \dynamic f \italic \small { 2nd } \hspace #0.1 \dynamic p
+}
+@end lilypond
+
+@seealso
+
+Manuel de notation : @ruser{Writing text}.
 
 
 @node Automatic and manual beams
 @subsection Automatic and manual beams
 
 @cindex ligatures manuelles
-Toutes les @rglos{beam} sont dessinées automatiquement :
+
+Glossaire musical : @rglos{beam}.
+
+Toutes les barres de ligature sont dessinées automatiquement :
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 a8 ais d ees r d c16 b a8
@@ -835,21 +914,27 @@ a8 ais d ees r d c16 b a8
 @noindent
 Lorsqu'on n'aime pas la manière dont les notes sont automatiquement
 groupées, il est possible de les ligaturer manuellement, en marquant la
-première note à attacher d'un @samp{[} et la dernière d'un @samp{]}.
+première note à attacher d'un crochet ouvrant @code{[} et la dernière
+d'un crochet fermant @code{]}.
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 a8[ ais] d[ ees r d] a b
 @end lilypond
 
+Pour désactiver les barres de ligature automatqiues pour des passages
+entiers, utilisez la commande @code{\autoBeamOff}, et utilisez
+@code{\autoBeamOn} pour les réactiver.
+
+@lilypond[verbatim,quote,relative=2]
+\autoBeamOff
+a8 c b4 d8. c16 b4
+\autoBeamOn
+a8 c b4 d8. c16 b4
+@end lilypond
+
 @seealso
-@quotation
-@table @asis
-@item Groupements de notes et ligatures automatiques
-voir @ruser{Automatic beams}.
-@item Groupements et ligatures manuels
-voir @ruser{Manual beams}.
-@end table
-@end quotation
+
+Manuel de notation : @ruser{Automatic beams}, @ruser{Manual beams}.
 
 
 @node Advanced rhythmic commands
@@ -860,9 +945,11 @@ voir @ruser{Manual beams}.
 @cindex mesure incomplète
 @subheading Partial measure
 
-Une levée (ou @rglos{anacrusis}) est entrée avec la commande
-@code{\partial}, suivie d'une durée : @code{\partial 4} est une levée
-d'une noire et @code{\partial 8} d'une croche.
+Glossaire musical : @rglos{anacrusis}.
+
+On crée une levée (ou anacrouse) avec la commande @code{\partial},
+suivie d'une durée : @code{\partial 4} produit une levée d'une noire
+et @code{\partial 8} d'une croche.
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \partial 8
@@ -872,11 +959,15 @@ f8 c2 d
 @cindex nolets
 @cindex triolets
 @subheading Tuplets
-Les nolets sont créés avec la commande @code{\times}, qui prend deux
-arguments : une fraction et une expression musicale.  La durée des notes
-de l'expression musicale est multipliée par la fraction.  Par exemple
-les notes d'un triolet durent les deux tiers du temps de leur notation
-réelle, cette fraction est donc de 2/3 pour les triolets :
+
+Glossaire musical : @rglos{note value}, @rglos{triplet}.
+
+Les @notation{nolets} sont créés avec la commande @code{\times}, qui
+prend deux arguments : une fraction et une expression musicale.  La
+durée des notes de l'expression musicale est multipliée par la
+fraction.  Par exemple les notes d'un @notation{triolet} durent les
+deux tiers de la durée de leur notation réelle, cette fraction est
+donc de 2/3 pour les triolets :
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 \times 2/3 { f8 g a }
@@ -888,11 +979,15 @@ réelle, cette fraction est donc de 2/3 pour les triolets :
 @cindex notes d'ornement
 @cindex ornementation
 @cindex appoggiature
+@cindex acciaccature
 @subheading Grace notes
 
-Des notes d'ornement sont produites par la commande @code{\grace}, mais
-aussi en préfixant une expression musicale avec le mot-clé
-@code{\appoggiatura} ou @code{\acciaccatura} :
+Glossaire musical : @rglos{grace notes}, @rglos{acciaccatura},
+@rglos{appoggiatura}.
+
+Des @notation{notes d'ornement} s'obtiennent en appliquant la commande
+@code{\grace}, @code{\appoggiatura} ou @code{\acciaccatura} à une
+expression musicale :
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 c2 \grace { a32[ b] } c2
@@ -901,33 +996,26 @@ c2 \acciaccatura b16 c2
 @end lilypond
 
 @seealso
-@quotation
-@table @asis
-@item Notes d'ornement
-voir @ruser{Grace notes},
-@item nolets
-voir @ruser{Tuplets},
-@item levées
-voir @ruser{Upbeats}.
-@end table
-@end quotation
+
+Manuel de notation : @ruser{Grace notes}, @ruser{Tuplets},
+@ruser{Upbeats}.
 
 
 @node Multiple notes at once
 @section Multiple notes at once
 
-Cette section traite des situations où l'on a plus d'une note à la fois
-: plusieurs instruments, plusieurs portées pour un même instrument (le
-piano, par exemple), et les accords.
+Cette section traite de situations où l'on a plus d'une note à la fois :
+plusieurs instruments, plusieurs voix ou portées pour un même
+instrument (le piano, par exemple), et les accords.
 
-La polyphonie, en théorie musicale, est la notion d'une musique
-constituée de plusieurs voix ; dans lilypond, ce terme désigne les
-situations où il y a plus d'une voix sur une même portée.
+En théorie musicale, la polyphonie désigne une musique constituée de
+plusieurs voix ; dans LilyPond, ce terme désigne les situations où il
+y a plus d'une voix sur une même portée.
 
 @menu
 * Music expressions explained::
 * Multiple staves::
-* Piano staves::
+* Staff groups::
 * Combining notes into chords::
 * Single staff polyphony::
 @end menu
@@ -936,24 +1024,26 @@ situations où il y a plus d'une voix sur une même portée.
 @node Music expressions explained
 @subsection Music expressions explained
 
+@cindex expression musicale
+
 Dans les fichiers source LilyPond, la musique est représentée par ce
 qu'on appelle des @emph{expressions musicales}.  En soi, une seule note
-peut constituer une expression musicale, si tant est qu'elle soit
-correctement encadrée :
+peut constituer une expression musicale :
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 a4
 @end lilypond
 
 Mettre un groupe de notes entre accolades crée une nouvelle expression
-musicale :
+musicale, appelée @emph{expression musicale composée}.  En voici un
+exemple avec deux notes :
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 { a4 g4 }
 @end lilypond
 
-Placer une séquence d'expressions musicales --- des notes par exemple
---- entre accolades signifie qu'elles doivent être jouées
+La mise entre accolades d'une séquence d'expressions musicales --- des
+notes par exemple --- signifie qu'elles doivent être jouées
 successivement, les unes après les autres.  Le résultat est une
 expression, qui peut elle-même être regroupée séquentiellement avec
 d'autres expressions.  Ici, l'expression de l'exemple précédent est
@@ -963,16 +1053,47 @@ combinée à deux notes :
 { { a4 g } f g }
 @end lilypond
 
+@cindex expression
+@subheading Analogy: mathematical expressions
+
+Ce mécanisme est similaire aux formules mathématiques : une grosse
+formule est créée en assemblant plusieurs petites formules.  De telles
+formules sont appelées expressions, elles ont une définition
+récursive, de telle sorte que vous pouvez fabriquer des expressions
+arbitrairement longues et complexes.  Par exemple :
+
+@example
+1
+
+1 + 2
+
+(1 + 2) * 3
+
+((1 + 2) * 3) / (4 * 5)
+@end example
+
+Ceci est une suite d'expressions, où chacune est contenue dans la
+suivante.  Les expressions les plus simples sont les nombres, et de
+plus grandes expressions sont produites en combinant des expressions
+avec des opérateurs --- comme @samp{+}, @samp{*} et @samp{/} --- et
+des parenthèses.  Tout comme les expressions mathématiques, les
+expressions musicales peuvent être imbriquées avec une profondeur
+arbitraire, ce qui est nécessaire pour des partitions complexes comme
+de la musique polyphonique.
+
+
 @subheading Simultaneous music expressions: multiple staves
 
-Cette technique est utile pour de la musique polyphonique.  Pour entrer
-une musique avec plusieurs voix ou plusieurs portées, nous pouvons aussi
-combiner en parallèle les expressions.  Deux voix qui doivent être
-jouées en même temps, sont entrées comme une combinaison simultanée de
-deux expressions.  Une expression musicale @q{simultanée} est formée en
-entourant les expressions entre @code{<<} et @code{>>}.  Dans l'exemple
-suivant, trois expressions (contenant chacune deux notes distinctes)
-sont combinées simultanément.
+Glossaire musical : @rglos{polyphony}.
+
+Cette technique est utile pour de la musique @notation{polyphonique}.
+Pour entrer une musique avec plusieurs voix ou plusieurs portées, nous
+pouvons aussi combiner @emph{en parallèle} les expressions : deux voix
+qui doivent être jouées en même temps, sont entrées comme une
+combinaison simultanée de deux expressions.  Une expression musicale
+@qq{simultanée} est formée en entourant les expressions entre @code{<<}
+et @code{>>}.  Dans l'exemple suivant, trois expressions (contenant
+chacune deux notes distinctes) sont combinées simultanément.
 
 @lilypond[quote,ragged-right,verbatim]
 \relative c'' {
@@ -984,21 +1105,21 @@ sont combinées simultanément.
 }
 @end lilypond
 
-Notez que nous avons ici indenté chaque niveau du fichier d'entrée avec
-un nombre d'espaces différent.  LilyPond se moque de l'espace qu'il peut
-y avoir (ou pas) au début d'une ligne, mais en indentant votre code vous
-le rendrez bien plus facile à lire pour les humains.
+Notez que nous avons ici indenté chaque niveau du fichier d'entrée
+avec un nombre d'espaces différent.  LilyPond se moque --- ou presque
+--- de l'espace qu'il peut y avoir ou non au début d'une ligne, mais
+un code bien indenté est bien plus lisible par des humains.
 
-@strong{Attention} : chaque note saisie est relative à la précédente,
-mais pas au @code{c''} de la commande @code{\relative} de départ.
+@warning{la hauteur de chaque note saisie est relative à la précédente,
+mais pas au @code{c''} de la commande @code{\relative} de départ.}
 
 
 @subheading Simultaneous music expressions: single staff
 
-Pour déterminer le nombre de portées, LilyPond regarde le premier
-élément autre qu'une accolade.  Si c'est une seule note, il y a une
-portée ; si c'est une expression simultanée, il y aura plus d'une
-portée.
+Pour déterminer le nombre de portées, LilyPond regarde le début
+de la première expression.  Si c'est une seule note, une seule portée
+est produite ; si c'est une expression simultanée, plusieurs portées
+sont produites.
 
 @lilypond[quote,ragged-right,verbatim]
 \relative c'' {
@@ -1007,49 +1128,21 @@ portée.
 }
 @end lilypond
 
-@cindex expression
-@cindex expression musicale
-@subheading Analogy: mathematical expressions
-
-Ce mécanisme est similaire au formules mathématiques : une grosse
-formule est créée en assemblant plusieurs petites formules.  Ces types
-de formules, appelées expressions, ont une définition récursive, de
-telle sorte que vous pouvez fabriquer des expressions arbitrairement
-longues et complexes.  Par exemple,
-
-@example
-1
-
-1 + 2
-
-(1 + 2) * 3
-
-((1 + 2) * 3) / (4 * 5)
-@end example
-
-Ceci est une suite d'expressions, où chacune est contenue dans la
-suivante.  Les expressions les plus simples sont les nombres, et de plus
-grandes expressions sont produites en combinant des expressions avec des
-opérateurs --- comme @samp{+}, @samp{*} et @samp{/} --- et des
-parenthèses.  Tout comme les expressions mathématiques, les expressions
-musicales peuvent être imbriquées avec une profondeur arbitraire, ce qui
-est nécessaire pour de la musique complexe comme des partitions
-polyphoniques.
-
 
 @node Multiple staves
 @subsection Multiple staves
 
-Comme nous l'avons vu dans @ref{Music expressions explained}, un fichier
-d'entrée LilyPond est fait d'expressions musicales.  Si la partition
-commence par plusieurs expressions simultanées, LilyPond créera
-plusieurs portées.  Cependant, il est plus facile de voir ce qu'il
-advient si l'on crée explicitement chacune des portées.
+Comme nous l'avons vu dans @ref{Music expressions explained}, un
+fichier d'entrée LilyPond est fait d'expressions musicales.  Si la
+partition commence par plusieurs expressions simultanées, LilyPond
+créera plusieurs portées.  Cependant, il est plus facile de prévoir le
+nombre de portées si on les crée explicitement, ce que nous allons
+voir.
 
-Pour créer plus d'une portée, chaque partie de la musique constituant
-une portée est entrée en la faisant précéder de @code{\new Staff}.  Ces
-éléments @code{Staff} sont ensuite combinés en parallèle avec @code{<<}
-et @code{>>}, comme ceci :
+Pour créer plus d'une portée, on ajoute @code{\new Staff} au début de
+chaque partie de la musique constituant une portée.  Ces éléments
+@code{Staff} sont ensuite combinés en parallèle avec @code{<<} et
+@code{>>}, comme ci-dessous.
 
 @lilypond[quote,ragged-right,verbatim]
 \relative c'' {
@@ -1066,26 +1159,29 @@ contexte de notation est un environnement dans lequel les événements
 musicaux --- comme les notes ou les commandes @code{\clef} --- sont
 interprétés.  Pour des pièces simples, ces contextes sont créés
 automatiquement.  Pour des pièces plus complexes, il est préférable de
-spécifier explicitement les contextes.  Cela assure que chaque fragment
-aura sa propre portée.
+spécifier explicitement les contextes, afin de s'assurer que chaque
+fragment aura sa propre portée.
 
-Il existe différents types de contextes.  Les contextes @code{Staff}
-(portée), @code{Voice} (voix) et @code{Score} (partition) gèrent la
+Il existe différents types de contextes.  Les contextes @code{Score}
+(partition), @code{Staff} (portée) et @code{Voice} (voix) gèrent la
 notation de la mélodie, alors que @code{Lyrics} gère les paroles et
-@code{ChordNames} imprime le nom des accords.
+@code{ChordNames} imprime des noms d'accords.
 
-En termes de syntaxe, faire précéder une expression musicale de
-@code{\new} crée une plus grosse expression musicale.  En reprenant la
-comparaison, cela ressemble au signe @qq{moins} en mathématiques.  La
-formule @math{(4+5)} est une expression, donc @math{-(4+5)} est une plus
-grosse expression.
+En termes de syntaxe, ajouter @code{\new} devant une expression
+musicale crée une plus grande expression musicale.  En reprenant la
+comparaison précédente, cela ressemble au signe @emph{moins} en
+mathématiques.  La formule @math{(4+5)} est une expression, donc
+@math{-(4+5)} est une plus grande expression.
 
 Les chiffres de métrique indiqués sur une portée affectent toutes les
-autres portées@footnote{Ce comportement peut être modifié si nécessaire,
-voir @ruser{Polymetric notation}.}.  En revanche l'armure d'une portée
-n'affecte @emph{pas} les autres portées.
-
-@lilypond[quote,ragged-right,verbatim]
+autres portées@footnote{Ce comportement peut être modifié si
+nécessaire, voir @ruser{Polymetric notation}.}.  En revanche l'armure
+d'une portée n'affecte @emph{pas} les autres portées.  Ces
+caractéristiques par défaut se justifient par le fait que
+l'utilisation d'instruments transpositeurs est bien plus fréquente que
+la musique polyrythmique.
+
+@lilypond[verbatim,quote]
 \relative c'' {
   <<
     \new Staff { \clef treble \time 3/4 c }
@@ -1095,17 +1191,21 @@ n'affecte @emph{pas} les autres portées.
 @end lilypond
 
 
+@node Staff groups
+@subsection Staff groups
 
+@cindex portée double
+@cindex portée pour piano
+@cindex piano, portée pour
+@cindex clavier, portée pour
 
-@node Piano staves
-@subsection Piano staves
+Glossaire musical : @rglos{brace}.
 
-@cindex changement de portée manuel
-@cindex voix changeant manuellement de portée
-La musique pour piano s'écrit sur deux portées reliées par une accolade.
-Imprimer ce type de portée revient au même que dans l'exemple de musique
-polyphonique de @ref{Multiple staves}, mais maintenant cette expression
-entière doit être interprétée dans un contexte @code{PianoStaff} :
+La musique pour piano s'écrit sur deux portées reliées par une
+@notation{accolade}.  La gravure de ce type de portée est semblable à
+l'exemple de musique polyphonique de @ref{Multiple staves}, mais
+maintenant cette expression entière est interprétée dans un contexte
+@code{PianoStaff} :
 
 @example
 \new PianoStaff <<
@@ -1126,32 +1226,37 @@ Voici un bref exemple :
 @end lilypond
 
 @seealso
-@quotation
-Voir @ruser{Keyboard instruments}.
-@end quotation
+
+Manuel de notation : @ruser{Keyboard instruments},
+@ruser{Displaying staves}.
 
 
 @node Combining notes into chords
 @subsection Combining notes into chords
 
-@cindex accords
-Des accords peuvent être produits en entourant les hauteurs de notes
-par des angles gauche et droit --- @samp{<} et @samp{>} ---
+@cindex accords, notes simultanées
 
-@lilypond[quote,fragment,verbatim,relative=2,fragment]
+Glossaire musical : @rglos{chord}.
+
+Nous avons vu précédemment comment combiner des notes simultanément,
+en les encadrant par des angles doubles @code{<<} et @code{>>}.  Pour
+produire des accords simples, c'est-à-dire une superposition de notes
+de même durée, on encadre les hauteurs de notes par des angles simples
+@code{<} et @code{>}, et on écrit la durée juste après.
+
+@lilypond[verbatim,quote,relative=2]
 r4 <c e g>4 <c f a>2
 @end lilypond
 
-Vous pouvez combiner les indications comme les liaisons et les ligatures
-de croches avec les accords.  Ils doivent cependant être placés en
-dehors des angles :
+Beaucoup d'éléments de notation que l'on peut attacher à une note
+simple, comme une liaison, un crochet indiquat un début ou fin de
+lien, un signe d'articulation, peuvent être également attachés à un
+accord : il faut ajouter ces indications après les hauteurs et la
+durée, donc @emph{à l'extérieur} des angles.
 
-@lilypond[quote,fragment,verbatim,relative=2,fragment]
+@lilypond[verbatim,quote,relative=2]
 r4 <c e g>8[ <c f a>]~ <c f a>2
-@end lilypond
-
-@lilypond[quote,fragment,verbatim,relative=2,fragment]
-r4 <c e g>8\>( <c e g> <c e g>4 <c f a>\!)
+r4 <c e g>8( <c e g>\> <c e g>4 <c f a>\!)
 @end lilypond
 
 
@@ -1166,10 +1271,9 @@ a ses propre hampes@footnote{familièrement appelées queues de note.},
 liaisons et ligatures, la voix supérieure ayant les hampes vers le haut,
 la voix inférieure vers le bas.
 
-Ce type de partition est réalisé en entrant chaque voix comme une
-séquence (avec @code{@{...@}}), en combinant simultanément les voix et
-en les séparant par @code{\\} :
-
+On réalise ce type de partition en entrant chaque voix comme une
+séquence, @emph{i.e.} avec @code{@{...@}}, puis en combinant
+simultanément les voix et en les séparant par @code{\\}.
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 <<
@@ -1181,8 +1285,8 @@ en les séparant par @code{\\} :
 Pour l'écriture de musique polyphonique, les silences invisibles
 s'avèrent bien pratiques : ce sont des silences qui ne s'impriment pas.
 Ils sont utiles pour remplir des voix qui, temporairement, ne jouent
-rien.  On peut voir ici le même exemple avec un silence invisible
-(@code{s}) à la place d'un silence normal (@code{r}) :
+rien.  Voici le même exemple que ci-dessus, avec un silence invisible
+@code{s} à la place d'un silence normal @code{r} :
 
 @lilypond[quote,ragged-right,verbatim,fragment,relative=2]
 <<
@@ -1209,9 +1313,8 @@ Là encore, ces expressions peuvent s'imbriquer arbitrairement :
 @end lilypond
 
 @seealso
-@quotation
-Voir @ruser{Basic polyphony}.
-@end quotation
+
+Manuel de notation : @ruser{Simultaneous notes}.
 
 
 @node Songs
@@ -1220,17 +1323,22 @@ Voir @ruser{Basic polyphony}.
 Cette section présente l'écriture vocale et les partitions de variété.
 
 @menu
-* Printing lyrics::
-* A lead sheet::
+* Setting simple songs::
+* Aligning lyrics to a melody::
+* Lyrics to multiple staves::
 @end menu
 
 
-@node Printing lyrics
-@subsection Printing lyrics
+@node Setting simple songs
+@subsection Setting simple songs
 
 @cindex paroles
 @cindex chansons
-Prenons une mélodie toute simple :
+
+Glossaire musical : @rglos{lyrics}.
+
+Prenons une mélodie toute simple, la comptine @emph{Girls and boys
+come out to play}.
 
 @lilypond[quote,ragged-right,verbatim]
 \relative c'' {
@@ -1239,9 +1347,9 @@ Prenons une mélodie toute simple :
 }
 @end lilypond
 
-Des paroles peuvent être associées à ces notes, en les combinant avec la
-commande @code{\addlyrics}.  Les paroles sont entrées en séparant chaque
-syllable par un espace :
+Des @notation{paroles} peuvent être associées à ces notes, en les
+combinant avec la commande @code{\addlyrics}.  On entre les paroles en
+séparant chaque syllable par un espace :
 
 @lilypond[quote,ragged-right,verbatim]
 <<
@@ -1253,152 +1361,345 @@ syllable par un espace :
 >>
 @end lilypond
 
+Remarquez les accolades embrassant la musique et celles embrassant les
+paroles, ainsi que les angles doubles encadrant toute la pièce ; ces
+derniers indiquent simplement que la musique et les paroles se
+produisent en même temps.
+
+
+@node Aligning lyrics to a melody
+@subsection Aligning lyrics to a melody
+
 @cindex mélisme
 @cindex ligne d'extension
-Cette mélodie se termine sur un @rglos{melisma}, c'est-à-dire qu'une
-seule syllable (@qq{free}) correspond à plus d'une note.  Ceci est
-indiqué avec une @emph{ligne d'extension}.  Elle est entrée avec deux
-caractères souligné (@code{_}), c'est-à-dire :
+@cindex trait d'union (paroles)
+@cindex caractère souligné (paroles)
+Glossaire musical : @rglos{melisma}, @rglos{extender line}.
 
-@lilypond[quote,ragged-right,verbatim]
+La ligne suivante de la comptine précédente est @emph{The moon doth
+shine as bright as day}.  Ajoutons-la au code.
+
+@lilypond[verbatim,quote]
 <<
   \relative c'' {
-    a4 e c8 e r4
-    b2 c4( d)
+    \key g \major
+    \time 6/8
+    d4 b8 c4 a8 d4 b8 g4
+    g8 a4 b8 c b a d4 b8 g4.
+  }
+  \addlyrics {
+    Girls and boys come out to play,
+    The moon doth shine as bright as day;
   }
-  \addlyrics { One day this shall be free __ }
 >>
 @end lilypond
 
-De la même manière, les séparations syllabiques d'un mot peuvent être
-entrées avec deux tirets (@code{-}), ce qui produit un tiret centré
-entre les deux syllabes :
+Remarquez que les paroles ajoutées ne s'alignent pas bien avec les
+notes.  Le mot @emph{shine} devrait être chanté sur deux notes au lieu
+d'une. On appelle ceci un @notation{mélisme} : il s'agit d'une seule
+syllabe chantée sur plus d'une note.  Il existe plusieurs façons
+d'étaler une sylabe sur plusieurs notes, la plus simple étant de lier
+les notes du mélisme.  Pour les détails, consultez @ref{Ties and
+slurs}.
 
-@c no ragged-right here because otherwise the hypens get lost.
-@lilypond[quote,verbatim]
+@lilypond[verbatim,quote]
 <<
-  \relative c' {
-    \time 2/4
-    f4 f c c
+  \relative c'' {
+    \key g \major
+    \time 6/8
+    d4 b8 c4 a8 d4 b8 g4
+    g8 a4 b8 c( b) a d4 b8 g4.
+  }
+  \addlyrics {
+    Girls and boys come out to play,
+    The moon doth shine as bright as day;
   }
-  \addlyrics { A -- le -- gri -- a }
 >>
 @end lilypond
 
-@seealso
-@quotation
-Plus de possibilités, comme celle d'ajouter plusieurs lignes de paroles
-en dessous d'une même mélodie sont exposées dans @ruser{Vocal music}.
-@end quotation
+Les paroles sont maintenant correctement alignées, mais les liens de
+croche automatiques ne conviennent pas pour les notes au-dessus de
+@emph{shine as}.  On peut les corriger en ajoutant des liens de croche
+manuels, pour ceci consultez @ref{Automatic and manual beams}.
 
+@lilypond[verbatim,quote]
+<<
+  \relative c'' {
+    \key g \major
+    \time 6/8
+    d4 b8 c4 a8 d4 b8 g4
+    g8 a4 b8 c([ b]) a d4 b8 g4.
+  }
+  \addlyrics {
+    Girls and boys come out to play,
+    The moon doth shine as bright as day;
+  }
+>>
+@end lilypond
 
-@node A lead sheet
-@subsection A lead sheet
+Au lieu d'utiliser une liaison, on peut indiquer le mélisme dans les
+paroles en insérant un caractère souligné @code{_} pour chaque note du
+mélisme sauf la première.
 
-@cindex partition de chanson
-@cindex chanson, partition complète
-@cindex accords, noms
-@cindex noms d'accords
+@lilypond[verbatim,quote]
+<<
+  \relative c'' {
+    \key g \major
+    \time 6/8
+    d4 b8 c4 a8 d4 b8 g4
+    g8 a4 b8 c[ b] a d4 b8 g4.
+  }
+  \addlyrics {
+    Girls and boys come out to play,
+    The moon doth shine _ as bright as day;
+  }
+>>
+@end lilypond
 
-En musique de variété, il est courant d'indiquer l'accompagnement par le
-nom des accords.  De tels accords peuvent être entrés comme les notes :
+Si une syllabe s'étend sur un grand nombre de notes ou une note très
+longue, on représente souvent le mélisme par un @notation{trait de
+prolongation}, qu'on entre avec @code{__}.  L'exemple suivant montre
+les trois premières mesures de la plainte de Didon, extraite de
+@emph{Didon et Énée} de Purcell.
 
-@lilypond[quote,ragged-right,verbatim]
-\chordmode { c2 f4. g8 }
+@lilypond[verbatim,quote]
+<<
+  \relative c'' {
+    \key g \minor
+    \time 3/2
+    g2 a bes bes( a)
+    b c4.( bes8 a4. g8 fis4.) g8 fis1
+  }
+  \addlyrics {
+    When I am laid,
+    am laid __ in earth,
+  }
+>>
 @end lilypond
 
-Maintenant, chaque hauteur est lue comme la base de l'accord à la place
-de la note.  Ce mode est activé avec @code{\chordmode}.  D'autres
-accords peuvent être créés en ajoutant des modificateurs après deux
-points.  L'exemple suivant montre quelques modificateurs usuels :
+Aucun exemple jusqu'à présent n'a utilisé de mots de plus d'une
+syllabe.  Dans des paroles, de tels mots sont écrits en syllabes
+séparées par des traits d'union.  Avec LilyPond, on utilise deux
+tirets pour produire un trait d'union centré entre deux syllabes.
+L'exemple suivant montre tout ce que nous avons vu jusqu'à maintenant
+sur l'alignement de paroles à une mélodie.
 
-@lilypond[quote,verbatim,ragged-right]
-\chordmode { c2 f4:m g4:maj7 gis1:dim7 }
+@c no ragged-right here because otherwise the hyphens get lost,
+@c but the example is long enough to avoid looking strange.
+@lilypond[verbatim,quote,noragged-right]
+<<
+  \relative c' {
+    \key g \major
+    \time 3/4
+    \partial 4
+    d4 g4 g a8( b) g4 g4
+    b8( c) d4 d e4 c2
+  }
+  \addlyrics {
+    A -- way in a __ man -- ger,
+    no __ crib for a bed, __
+  }
+>>
 @end lilypond
 
-Pour la musique improvisée, les accords ne sont pas imprimés sur des
-portées mais comme des lignes à part entière.  Ceci s'obtient en
-utilisant @code{\chords} à la place de @code{\chordmode}.  La même
-syntaxe sera utilisée que dans le cas de@code{\chordmode}, mais le rendu
-des notes interviendra dans un contexte @code{ChordNames}, avec le
-résultat suivant :
-
-@lilypond[quote,verbatim,ragged-right]
-\chords { c2 f4.:m g4.:maj7 gis8:dim7 }
+Avec certaines paroles, en particulier en italien, il se produit la
+situation inverse : il peut y avoir plusieurs syllabes sur une seule
+note.  On réalise ceci avec LilyPond grâce à un caractère souligné
+@code{_} sans espace entre les syllabes, ou alors en groupant les
+syllabes avec des guillemets.  L'exemple suivant est extrait de l'air
+de Figaro @emph{Largo al factotum}, dans @emph{Figaro} de Rossini, où
+la syllabe @emph{al} est chantée sur la même note que @emph{go}.
+
+@c no ragged-right here because otherwise the hyphens get lost,
+@c but the example is long enough to avoid looking strange.
+@lilypond[verbatim,quote,noragged-right]
+<<
+  \relative c' {
+    \clef bass
+    \key c \major
+    \time 6/8
+    c4.~ c8 d b c([ d]) b c d b c
+  }
+  \addlyrics {
+    Lar -- go_al fac -- to -- tum del -- la cit -- tà
+  }
+>>
 @end lilypond
 
-@cindex partition de chanson
-@cindex chanson, partition complète
-Une fois assemblés, les accords, paroles et mélodie forment une
-partition de chanson :
+@seealso
 
-@lilypond[quote,verbatim,ragged-right]
+Manuel de notation : @ruser{Vocal music}.
+
+
+@node Lyrics to multiple staves
+@subsection Lyrics to multiple staves
+
+La méthode simple d'ajout de paroles avec @code{\addlyrics} peut être
+également utilisée pour placer des paroles sous plusieurs portées.
+L'exemple suivant est extrait de @emph{Judas Macchabée} de Händel.
+
+@lilypond[verbatim,quote]
 <<
-  \chords { c2 g:sus4 f e }
   \relative c'' {
-    a4 e c8 e r4
-    b2 c4( d)
+    \key f \major
+    \time 6/8
+    \partial 8
+    c8 c([ bes]) a a([ g]) f f'4. b, c4.~ c4
+  }
+  \addlyrics {
+    Let flee -- cy flocks the hills a -- dorn, __
+  }
+  \relative c' {
+    \key f \major
+    \time 6/8
+    \partial 8
+    r8 r4. r4 c8 a'([ g]) f f([ e]) d e([ d]) c bes'4
+  }
+  \addlyrics {
+    Let flee -- cy flocks the hills a -- dorn,
   }
-  \addlyrics { One day this shall be free __ }
 >>
 @end lilypond
 
+Pour produire des partitions plus complexes ou plus longues que cet
+exemple simple, il est vivement conseillé de séparer la structure de
+la partition des notes et paroles, grâce à des variables.  Ceci sera
+détaillé plus loin dans @ref{Organizing pieces with variables}.
 
 @seealso
-@quotation
-Une liste complète de modificateurs et d'autres options de mise en forme
-se trouve à la section @ruser{Chord notation}.
-@end quotation
+
+Manuel de notation : @ruser{Vocal music}.
+
 
 
 @node Final touches
 @section Final touches
 
-L'ultime section de ce tutoriel montre comment ajouter une touche finale
-à des morceaux simples, et consititue une introduction au reste du
-manuel.
+L'ultime section de ce tutoriel montre comment ajouter une touche
+finale à des morceaux simples, et constitue une introduction au reste
+du manuel.
 
 @menu
+* Organizing pieces with variables::
 * Version number::
 * Adding titles::
 * Absolute note names::
-* Organizing pieces with identifiers::
 * After the tutorial::
-* How to read the manual::
 @end menu
 
 
+@node Organizing pieces with variables
+@subsection Organizing pieces with variables
+
+Lorsque l'on combine tous les éléments étudiés précédemment pour
+écrire des partitions plus longues, les expressions musicales prennent
+de l'ampleur et, dans le cas des pièces polyphoniques, deviennent
+profondément imbriquées, jusqu'au point où il devient difficile de se
+repérer dans le fichier source.  Cet inconvénient peut être résolu par
+l'utilisation de @emph{variables}.
+
+En utilisant des variables, parfois appelées identificateurs ou
+macros, on peut scinder des expressions musicales complexes en des
+expressions plus simples.  Une variable se définit comme suit :
+
+@example
+musiqueToto = @{ @dots{} @}
+@end example
+
+Le contenu de l'expression musicale @code{musiqueToto} pourra être
+utilisé plus loin en faisant précéder son nom d'un anti-slash,
+c'est-à-dire @code{\musiqueToto}, tout comme n'importe quelle commande
+LilyPond.  Toute variable doit être définie @emph{avant} son
+utilisation dans une autre expression musicale.
+
+@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
+  >>
+}
+@end lilypond
+
+@noindent
+Le nom d'une variable ne doit comporter que des caractères
+alphabétiques non accentués, aucun nombre ni tiret ne sont autorisés.
+
+On peut utiliser une variable déjà définie autant de fois que l'on
+veut, y compris dans la définition d'une nouvelle variable ; par
+exemple, cela peut servir à saisir un motif qu'une seule fois, même
+s'il se répète un grand nombre de fois dans la pièce.
+
+@lilypond[verbatim,quote]
+tripletA = \times 2/3 { c,8 e g }
+barA = { \tripletA \tripletA \tripletA \tripletA }
+
+\relative c'' {
+ \barA \barA
+}
+@end lilypond
+
+Il est possible d'utiliser des variables de types variés.  Par exemple,
+
+@example
+width = 4.5\cm
+name = "Wendy"
+aFivePaper = \paper @{ paperheight = 21.0 \cm @}
+@end example
+
+En fonction de son contenu, un identificateur peut être utilisé à
+différents endroits.  L'exemple suivant utilise les variable définies
+ci-dessus.
+
+@example
+\paper @{
+  \aFivePaper
+  line-width = \width
+@}
+@{ c4^\name @}
+@end example
+
+
 @node Version number
 @subsection Version number
 
 @cindex versions
 La déclaration @code{\version} stipule le numéro de la version de
-LilyPond pour laquelle le fichier a été écrit,
+LilyPond pour laquelle le fichier a été écrit :
 
 @example
 \version @w{"@version{}"}
 @end example
 
 @noindent
-que l'on place par convention en début de fichier.
+Par convention, on place cette instruction en début de fichier.
 
-Cette annotation permet de faciliter les prochaines mises à jour de
-LilyPond.  Les changements dans la syntaxe sont gérés avec un programme
-spécial, @file{convert-ly} --- voir @rprogram{Updating files with convert-ly}
---- et il utilise @code{\version} pour déterminer les règles de
-conversion à appliquer au fichier.
+Cette instruction permet de faciliter les mises à jour futures de
+LilyPond.  Les changements de syntaxe au fil des versions sont gérés
+avec un programme dédié, @command{convert-ly}, qui utilise la valeur
+de @code{\version} pour déterminer les règles de conversion à
+appliquer au fichier source.  Pour plus d'informations, consultez voir
+@rprogram{Updating files with convert-ly}.
 
 
 @node Adding titles
 @subsection Adding titles
 
-Les informations bibliographiques (nom du morceau, du compositeur, etc)
-sont entrées dans un bloc séparé, le bloc d'en-tête (@code{\header}),
-qui existe indépendamment des expressions musicales principales.  Le
-bloc @code{\header} est habituellement placé en début de fichier.
+On indique les informations bibliographiques --- nom du morceau, du
+compositeur, numéro d'opus... --- dans un bloc à part, le bloc
+d'en-tête @code{\header}, qui existe indépendamment de l'expression
+musicale principale.  Le bloc @code{\header} est habituellement placé
+en début de fichier, après le numéro de version.
 
 @example
-\version "2.11.51"
+\version @w{"@version{}"}
 \header @{
   title = "Symphonie"
   composer = "Moi"
@@ -1406,26 +1707,28 @@ bloc @code{\header} est habituellement placé en début de fichier.
 @}
 
 @{
- @dots{} music @dots{}
+ @dots{} la musique @dots{}
 @}
 @end example
-Quand le fichier est traité, le titre et le compositeur sont imprimés en
-haut de la partition.  Vous trouverez plus d'informations sur les titres
-à @ruser{Creating titles}.
+
+Quand LilyPond traite le fichier, le titre et le compositeur sont
+imprimés au début de la partition.  Vous trouverez plus d'informations
+sur les titres à la section @ruser{Creating titles}.
+
 
 @node Absolute note names
 @subsection Absolute note names
 
-Jusqu'ici nous n'avons utilisé que le mode @code{\relative} pour définir
-les hauteurs de notes.  Si c'est effectivement le moyen le plus simple
-d'entrer la majeure partie de votre musique, il existe une autre façon
-de procéder : le mode des hauteurs absolues.
+Jusqu'ici nous n'avons utilisé que le mode @code{\relative} pour
+définir les hauteurs de notes.  Si c'est souvent le moyen le plus
+simple de saisir la musique au clavier, il existe une autre façon de
+procéder : le mode de hauteurs absolues.
 
 Si vous omettez la commande @code{\relative}, LilyPond considérera
-toutes les hauteurs comme des hauteurs absolues.  Un @code{c'} sera
-toujours un do du milieu, un @code{b} sera toujours une note au-dessous
-du précédent, et un @code{g,} sera toujours la note la plus grave dans
-la portée de clé de fa.
+toutes les hauteurs comme des hauteurs absolues.  Un @code{c'} désigne
+toujours le do central, un @code{b} se situe une seconde en dessous
+du do central, et un @code{g,} est situé sur la première ligne de
+la portée en clé de fa.
 
 @lilypond[quote,verbatim,ragged-right]
 {
@@ -1452,8 +1755,9 @@ Voici une gamme sur 4 octaves :
 }
 @end lilypond
 
-Comme vous pouvez le voir, il faut beaucoup d'apostrophes pour écrire de
-la musique dans un registre aigu.  Regardez cet extrait de Mozart :
+Comme vous pouvez le voir, il faut beaucoup d'apostrophes pour écrire
+de la musique dans un registre aigu, comme le montre cet extrait de
+Mozart.
 
 @lilypond[quote,verbatim,ragged-right]
 {
@@ -1464,9 +1768,10 @@ la musique dans un registre aigu.  Regardez cet extrait de Mozart :
 }
 @end lilypond
 
-Toutes ces apostrophes rendent le fichier moins lisible, et c'est donc
-une source d'erreurs.  En mode @code{\relative}, le même exemple devient
-bien plus facile à lire :
+Toutes ces apostrophes rendent le fichier moins lisible, et surtout il
+est très probable d'oublier au moins une apostrophe au cours de la
+frappe.  En mode @code{\relative}, le même exemple devient bien plus
+facile à lire et à saisir.
 
 @lilypond[quote,verbatim,ragged-right]
 \relative c'' {
@@ -1478,120 +1783,39 @@ bien plus facile à lire :
 @end lilypond
 
 Si d'aventure vous faites une erreur d'octaviation, le mode
-@code{\relative} la rendra frappante --- toutes les notes suivantes
-seront placées à la mauvaise octave.  En mode de hauteurs absolues, une
-erreur isolée ne serait pas auntant visible, et donc aussi facile à
-dénicher.
-
-Cependant, le mode de hauteurs absolues reste utile pour les musiques où
-les intervalles sont étendus, surtout pour les fichiers LilyPond créés
-par ordinateur.
-
-
-@node Organizing pieces with identifiers
-@subsection Organizing pieces with identifiers
-
-Lorsque l'on combine tous les éléments étudiés plus haut pour produire
-des fichiers plus volumineux, les blocs @code{\score} deviennent
-beaucoup plus gros parce que les expressions musicales sont plus longues
-et, dans le cas des pièces polyphoniques, profondément imbriquées.  De
-telles expressions imposantes finissent par devenir peu maniables.  Cet
-inconvénient peut être résolu par l'utilisation
-d'@emph{identificateurs}.
-
-En utilisant ces identificateurs, que l'on pourrait aussi appeler
-variables ou macros, il est possible de découper des expressions
-musicales complexes.  Un identificateur se définit comme suit :
+@code{\relative} la mettra en évidence : toutes les notes suivantes
+seront placées à la mauvaise octave.  En mode de hauteurs absolues,
+une erreur isolée ne serait pas autant visible, donc serait plus
+difficile à dénicher.
 
-@example
-MusiqueToto = @{ @dots{} @}
-@end example
-
-Le contenu de l'expression musicale @code{MusiqueToto} pourra être
-utilisé plus loin en faisant précéder son nom d'un anti-slash,
-c'est-à-dire @code{\MusiqueToto}, juste comme n'importe quelle commande
-LilyPond.  Tous les identificateurs doivent être définis @emph{avant}
-l'expression musicale principale.
-
-@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
-  >>
-}
-@end lilypond
-
-@noindent
-Le nom d'un identificateur ne doit comporter que des caractères
-alphabétiques non accentués, aucun nombre ni tiret.
-
-Il est possible d'utiliser des variables de types variés.  Par exemple,
-
-@example
-width = 4.5\cm
-name = "Wendy"
-aFivePaper = \paper @{ paperheight = 21.0 \cm @}
-@end example
-
-En fonction de son contenu, un identificateur peut être utilisé à
-différents endroits.  L'exemple suivant utilise la variable ci-dessus :
-
-@example
-\paper @{
-  \aFivePaper
-  line-width = \width
-@}
-@{ c4^\name @}
-@end example
+Cependant, le mode de hauteurs absolues reste utile pour les musiques
+où les intervalles sont étendus, et plus encore pour les fichiers
+LilyPond créés par des programmes.
 
 
 @node After the tutorial
 @subsection After the tutorial
 
-Après avoir parcouru ce tutoriel, vous devriez vous essayer à écrire un
-morceau ou deux.  Commencez par copier l'un des @ref{Templates} types et
-ajoutez-y des notes.  Si vous voulez employer une notation que vous
-n'avez pas trouvé dans le tutoriel, consultez la référence de notation,
-en commençant par la @ruser{Musical notation}.  Si vous désirez écrire pour
-un ensemble instrumental non couvert par les @ref{Templates}, lisez la
-section @ref{Extending the templates}.
-
-Après avoir écrit quelques pièces courtes, lisez les chapitres 3 à 5 du
-manuel d'apprentissage.  Rien ne s'oppose à ce que vous consultiez dès à
-présent les autres chapitres, bien sûr ! Néanmoins, le reste du manuel
-de l'utilisateur part du principe que vous avez déjà bien assimilé la
-syntaxe de LilyPond.  Vous pouvez toujours survoler le reste du manuel,
-et y revenir plus tard après avoir acquis de l'expérience.
-
-@node How to read the manual
-@subsection How to read the manual
-
-Comme nous l'avons déjà vu dans @ref{How to read the tutorial}, de
-nombreux exemples du tutoriel n'ont pas fait apparaître
-@code{\relative c'' @{ ...  @}} dans l'extrait de code affiché.
-
-Dans le reste du manuel, les exemples utilisés sont encore beaucoup plus
-souples : parfois il leur manque le @code{\relative c'' @{ ...  @}},
-mais d'autres fois ils ont recours à une autre hauteur de référence,
-telle que @code{c'} ou @code{c,,}), et dans certains cas c'est même
-l'exemple entier qui est en mode de hauteurs absolues !  Cependant, de
-telles ambiguïtés ne se trouvent que dans des contextes où les hauteurs
-n'ont que peu d'importance.  Dans tous les exemples où elles en ont, le
-mode @code{\relative} ou absolu @code{@{ @}} est explicitement spécifié.
-
-Si vous ne vous y retrouvez toujours pas pour savoir quel code LilyPond
-produit précisément tel ou tel exemple, consultez la version HTML de ce
-manuel si ce n'est pas déjà le cas, et cliquez sur l'image de la
-partition.  La source exacte utilisée pour générer ce manuel s'affichera
-alors.
-
-Pour en savoir plus sur l'organisation de la suite de ce manuel,
-reportez-vous à @ref{About the documentation}.
+Après avoir parcouru ce tutoriel, vous devriez essayer d'écrire un
+morceau ou deux.  Commencez par copier l'un des modèles types et
+ajoutez-y des notes --- consultez les @ref{Templates}.  Si vous voulez
+employer une notation que vous n'avez pas trouvé dans le tutoriel,
+consultez le manuel de notation, en commençant par la @ruser{Musical
+notation}.  Si vous désirez écrire pour un ensemble instrumental non
+couvert par les modèles, lisez la section @ref{Extending the
+templates}.
+
+Après avoir écrit quelques pièces courtes, lisez les chapitres 3 à 5
+du manuel d'initiation.  Rien ne s'oppose à ce que vous consultiez dès
+à présent ces chapitres, bien sûr ! Néanmoins, le reste du manuel
+d'initiation part du principe que vous avez déjà bien assimilé la
+syntaxe de base de LilyPond.  Vous pouvez toujours survoler ces
+chapitres 3 à 5, et y revenir plus tard après avoir acquis de
+l'expérience.
+
+Si vous ne l'avez pas encore fait, lisez @ref{About the
+documentation}.  Les sources de documentation et d'information sur
+LilyPond sont vastes, il est normal pour un débutant de ne pas savoir
+où chercher ; si vous passez quelques minutes à lire attentivement
+cette section, vous vous épargnerez certainement la frustration causée
+par des heures de recherche infructueuses.
diff --git a/Documentation/fr/user/working.itely b/Documentation/fr/user/working.itely
index 7086f337b4..bd8b7d4637 100644
--- a/Documentation/fr/user/working.itely
+++ b/Documentation/fr/user/working.itely
@@ -21,13 +21,13 @@ ces astuces peuvent vous paraître évidentes, mais vous ne perdrez tout
 de même pas votre temps à lire ce chapitre.
 
 @menu
-* Suggestions for writing LilyPond files::  
+* Suggestions for writing LilyPond input files::
 * When things don't work::      
 * Scores and parts::            
 @end menu
 
-@node Suggestions for writing LilyPond files
-@section Suggestions for writing LilyPond files
+@node Suggestions for writing LilyPond input files
+@section Suggestions for writing LilyPond input files
 
 Maintenant vous êtes prêt à travailler sur de plus gros fichiers
 LilyPond --- des pièces entières, et plus seulement les petits
@@ -208,9 +208,9 @@ 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 }
+fragmentA = \relative c'' { a4 a8. b16 }
+fragmentB = \relative c'' { a8. gis16 ees4 }
+violin = \new Staff { \fragmentA \fragmentA \fragmentB \fragmentA }
 \score {
   {
     \violin
diff --git a/Documentation/po/de.po b/Documentation/po/de.po
index f1b0922d4c..6d7dd10865 100644
--- a/Documentation/po/de.po
+++ b/Documentation/po/de.po
@@ -5191,7 +5191,7 @@ msgstr "Textbeschriftung (Einleitung)"
 #. @subsubsection in Documentation/user/text.itely
 #. @node in Documentation/es/user/text.itely
 #. @subsubsection in Documentation/es/user/text.itely
-msgid "Common markup commands"
+msgid "Selecting font and font size"
 msgstr "Überblick über die wichtigsten Textbeschriftungsbefehle"
 
 #. @node in Documentation/user/text.itely
diff --git a/Documentation/po/es.po b/Documentation/po/es.po
index 932d72f70c..028ebbcbeb 100644
--- a/Documentation/po/es.po
+++ b/Documentation/po/es.po
@@ -5231,7 +5231,7 @@ msgstr "Introducción al marcado de texto"
 #. @subsubsection in Documentation/user/text.itely
 #. @node in Documentation/es/user/text.itely
 #. @subsubsection in Documentation/es/user/text.itely
-msgid "Common markup commands"
+msgid "Selecting font and font size"
 msgstr "Instrucciones de marcado de texto más usuales"
 
 # fuzzy. FVD
diff --git a/Documentation/po/fr.po b/Documentation/po/fr.po
index ff19e5f4b2..7c0cb10cb7 100644
--- a/Documentation/po/fr.po
+++ b/Documentation/po/fr.po
@@ -5162,7 +5162,7 @@ msgstr "Introduction aux étiquettes de texte"
 #. @subsubsection in Documentation/user/text.itely
 #. @node in Documentation/es/user/text.itely
 #. @subsubsection in Documentation/es/user/text.itely
-msgid "Common markup commands"
+msgid "Selecting font and font size"
 msgstr "Vue d'ensemble des commandes d'indication textuelle"
 
 #. @node in Documentation/user/text.itely
diff --git a/Documentation/po/lilypond-doc.pot b/Documentation/po/lilypond-doc.pot
index fc6030d94e..b91accfe19 100644
--- a/Documentation/po/lilypond-doc.pot
+++ b/Documentation/po/lilypond-doc.pot
@@ -5148,7 +5148,7 @@ msgstr ""
 #. @subsubsection in Documentation/user/text.itely
 #. @node in Documentation/es/user/text.itely
 #. @subsubsection in Documentation/es/user/text.itely
-msgid "Common markup commands"
+msgid "Selecting font and font size"
 msgstr ""
 
 #. @node in Documentation/user/text.itely
diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index 1f92554435..9008885014 100644
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -7,11 +7,12 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.51"
+@c \version "2.11.55"
 
 @node Changing defaults
 @chapter Changing defaults
 
+@strong{N.B. This Chapter is under heavy development at present.}
 
 The purpose of LilyPond's design is to provide the finest output
 quality as a default.  Nevertheless, it may happen that you need to
@@ -121,7 +122,17 @@ further explanation and with links to the IR.
 
 @c TODO Add introduction which explains contexts in generality  -td
 
-@unnumberedsubsec Score - the master of all contexts
+Contexts are arranged heirarchically:
+
+@menu
+* Score - the master of all contexts::
+* Top-level contexts - staff containers::
+* Intermediate-level contexts - staves::
+* Bottom-level contexts - voices::
+@end menu
+
+@node Score - the master of all contexts
+@unnumberedsubsubsec Score - the master of all contexts
 
 This is the top level notation context. No other context can
 contain a Score context. By default the Score context handles
@@ -134,115 +145,118 @@ A Score context is instantiated implicitly when a
 processed, or explicitly when a @code{\new Score} command is
 executed.
 
-@subheading Top-level contexts: Staff containers
+@node Top-level contexts - staff containers
+@unnumberedsubsubsec Top-level contexts - staff containers
 
-@subsubheading StaffGroup
+@strong{@emph{StaffGroup}}
 
 Groups staves while adding a bracket on the left side, grouping
 the staves together. The bar lines of the contained staves are
 connected vertically. StaffGroup only consists of a collection
 of staves, with a bracket in front and spanning bar lines.
 
-@unnumberedsubsubsec ChoirStaff
+@strong{@emph{ChoirStaff}}
 
 Identical to StaffGroup except that the bar lines of the contained
 staves are not connected vertically.
 
-@unnumberedsubsubsec GrandStaff
+@strong{@emph{GrandStaff}}
 
 A group of staves, with a brace on the left side, grouping
 the staves together. The bar lines of the contained staves are
 connected vertically.
 
-@unnumberedsubsubsec PianoStaff
+@strong{@emph{PianoStaff}}
 
 TODO No longer correct?  Check.  -td
 
 Just like GrandStaff but with a forced distance between the
 staves, so cross staff beaming and slurring can be used.
 
-@unnumberedsubsubsec DrumStaff
-
-Handles typesetting for percussion. Can contain DrumVoice
-
-@unnumberedsubsubsec InnerStaffGroup
+@strong{@emph{InnerStaffGroup}}
 
 TODO  -td
 
-@unnumberedsubsubsec InnerChoirStaff
+@strong{@emph{InnerChoirStaff}}
 
 TODO  -td
 
-@heading Staff-level contexts
+@node Intermediate-level contexts - staves
+@unnumberedsubsubsec Intermediate-level contexts - staves
 
-@unnumberedsubsubsec Staff
+@strong{@emph{Staff}}
 
 Handles clefs, bar lines, keys, accidentals. It can contain
 Voice contexts.
 
-@unnumberedsubsubsec RhythmicStaff
+@strong{@emph{RhythmicStaff}}
 
 Like Staff but for printing rhythms. Pitches are ignored;
 the notes are printed on one line.
 
-@unnumberedsubsubsec TabStaff
+@strong{@emph{TabStaff}}
 
 Context for generating tablature. By default lays the music
 expression out as a guitar tablature, printed on six lines.
 
-@unnumberedsubsubsec VaticanaStaff
+@strong{@emph{DrumStaff}}
+
+Handles typesetting for percussion. Can contain DrumVoice
+
+@strong{@emph{VaticanaStaff}}
 
 Same as Staff, except that it is designed for typesetting
 a piece in gregorian style.
 
-@unnumberedsubsubsec MensuralStaff
+@strong{@emph{MensuralStaff}}
 
 Same as Staff, except that it is designed for typesetting
 a piece in mensural style.
 
-@unnumberedsubsec Voice-level (bottom) contexts
+@node Bottom-level contexts - voices
+@unnumberedsubsubsec Bottom-level contexts - voices
 
 Voice-level contexts initialise certain properties and start
 appropriate engravers.  Being bottom-level contexts, they cannot
 contain other contexts.
 
-@unnumberedsubsubsec Voice
+@strong{@emph{Voice}}
 
 Corresponds to a voice on a staff. This context handles the
 conversion of dynamic signs, stems, beams, super- and sub-scripts,
 slurs, ties, and rests.  You have to instantiate this explicitly
 if you require multiple voices on the same staff.
 
-@unnumberedsubsubsec VaticanaVoice
+@strong{@emph{VaticanaVoice}}
 
 Same as Voice, except that it is designed for typesetting a piece
 in gregorian style.
 
-@unnumberedsubsubsec MensuralVoice
+@strong{@emph{MensuralVoice}}
 
 Same as Voice, with modifications for typesetting a piece in
 mensural style.
 
-@unnumberedsubsubsec Lyrics
+@strong{@emph{Lyrics}}
 
 Corresponds to a voice with lyrics. Handles the printing of a
 single line of lyrics.
 
-@unnumberedsubsubsec DrumVoice
+@strong{@emph{DrumVoice}}
 
 The voice context used in a percussion staff.
 
-@unnumberedsubsubsec FiguredBass
+@strong{@emph{FiguredBass}}
 
 The context in which BassFigure objects are created from
 input entered in @code{\figuremode} mode.
 
-@unnumberedsubsubsec TabVoice
+@strong{@emph{TabVoice}}
 
 The voice context used within a TabStaff context.  Usually left to
 be created implicitly.
 
-@unnumberedsubsubsec ChordNames
+@strong{@emph{ChordNames}}
 
 Typesets chord names.
 
@@ -787,10 +801,10 @@ ossia = { f4 f f f }
 
 
 @menu
-* Navigating the program reference::  
-* Layout interfaces::           
-* Determining the grob property::  
-* Naming conventions::          
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Naming conventions::
 @end menu
 
 @node Navigating the program reference
@@ -1084,7 +1098,7 @@ Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
 @subsection Naming conventions
 
 Another thing that is needed, is an overview of the various naming
-conventions: 
+conventions:
 
     scheme functions: lowercase-with-hyphens (incl. one-word
 names)
@@ -1108,11 +1122,11 @@ LP-specific?
 @section Modifying properties
 
 @menu
-* Overview of modifying properties::  
-* The \set command::            
-* The \override command::       
-* \set versus \override::       
-* Objects connected to the input::  
+* Overview of modifying properties::
+* The \set command::
+* The \override command::
+* \set versus \override::
+* Objects connected to the input::
 @end menu
 
 
@@ -1729,13 +1743,348 @@ restricted to a sub-set of the spanners.
 
 @c TODO Add new subsection Shapes of objects
 @c which would include Slur shapes
-@c with a Known issue: can't modify shapes if there are
+@c with a Known issue: can't modify shapes with 'control-points if there are
 @c more than one at the same musical moment
 
 @node Controlling visibility of objects
 @subsection Controlling visibility of objects
 
-@c FIXME Write this section
+@cindex objects, visibility of
+@cindex grobs, visibility of
+@cindex visibility of objects
+
+There are four main ways in which the visibility of layout objects
+can be controlled: their stencil can be removed, they can be made
+transparent, they can be colored white, or their
+@code{break-visibility} property can be overridden.  The first
+three apply to all layout objects; the last to just a few -- the
+@emph{breakable} objects.  The Learning Manual introduces these
+four techniques, see @rlearning{Visibility and color of objects}.
+
+There are also a few other techniques which are specific to
+certain layout objects.  These are covered under Special
+considerations.
+
+@menu
+* Removing the stencil::
+* Making objects transparent::
+* Painting objects white::
+* Using break-visibility::
+* Special considerations::
+@end menu
+
+
+@node Removing the stencil
+@unnumberedsubsubsec Removing the stencil
+
+@cindex stencil, removing
+
+Every layout object has a stencil property.  By default this is set
+to the specific function which draws that object.  If this property
+is overridden to @code{#f} no function will be called and the object
+will not be drawn.  The default action can be recovered with
+@code{\revert}.
+
+@lilypond[quote,verbatim,relative=1]
+a1 a
+\override Score.BarLine #'stencil = ##f
+a a
+\revert Score.BarLine #'stencil
+a a a
+@end lilypond
+
+@node Making objects transparent
+@unnumberedsubsubsec Making objects transparent
+
+@cindex transparent, making objects
+
+Every layout object has a transparent property which by default is
+set to @code{#f}.  If set to @code{#t} the object still occupies
+space but is made invisible.
+
+@lilypond[quote,verbatim,relative=2]
+a4 a
+\once \override NoteHead #'transparent = ##t
+a a
+@end lilypond
+
+@node Painting objects white
+@unnumberedsubsubsec Painting objects white
+
+@cindex objects, coloring
+@cindex coloring objects
+@cindex layers
+@cindex printing order
+@cindex overwriting objects
+@cindex objects, overwriting
+@cindex grobs, overwriting
+
+Every layout object has a color property which by default is set
+to @code{black}.  If this is overridden to @code{white} the object
+will be indistinguishable from the white background.  However,
+if the object crosses other objects the color of the crossing
+points will be determined by the order in which they are drawn,
+and this may leave a ghostly image of the white object, as shown
+here:
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.Clef #'color = #white
+a1
+@end lilypond
+
+This may be avoided by changing the order of printing the objects.
+All layout objects have a @code{layer} property which should be set
+to an integer.  Objects with the lowest value of @code{layer} are
+drawn first, then objects with progressively higher values are drawn,
+so objects with higher values overwrite objects with lower values.
+By default most objects are assigned a @code{layer} value of
+@code{1}, although a few objects, including @code{StaffSymbol} and
+@code{BarLine}, are assigned a value of @code{0}.  The order of
+printing objects with the same value of @code{layer} is indeterminate.
+
+In the example above the white clef, with a default @code{layer}
+value of @code{1}, is drawn after the staff lines (default
+@code{layer} value @code{0}), so overwriting them.  To change this,
+the @code{Clef} object must be given in a lower value of
+@code{layer}, say @code{-1}, so that it is drawn earlier:
+
+@lilypond[quote,verbatim,relative=2]
+\override Staff.Clef #'color = #white
+\override Staff.Clef #'layer = #-1
+a1
+@end lilypond
+
+@node Using break-visibility
+@unnumberedsubsubsec Using break-visibility
+
+@cindex break-visibility
+
+Most layout objects are printed only once, but some like
+bar lines, clefs, time signatures and key signatures, may need
+to be printed twice when a line break occurs -- once at the end
+of the line and again at the start of the next line.  Such
+objects are called @emph{breakable}, and have a property, the
+@code{break-visibility} property to control their visibility
+at the three positions in which they may appear -- at the
+start of a line, within a line if they are changed, and at the
+end of a line if a change takes place there.
+
+For example, the time signature
+by default will be printed at the start of the first line, but
+nowhere else unless it changes, when it will be printed at the
+point at which the change occurs.  If this change occurs at the
+end of a line the new time signature will be printed at the start
+of the next line and a cautionary time signature will be printed
+at the end of the previous line as well.
+
+This behaviour is controlled by the @code{break-visibility}
+property, which is explained in @rlearning{Visibility and color of
+objects}.  This property takes a vector of three booleans which,
+in order, determine whether the object is printed at the end of,
+within the body of, or at the beginning of a line.  Or to be more
+precise, before a line break, where there is no line break, or
+after a line break.
+
+Alternatively, seven of the eight combinations may be specified
+by pre-defined functions, defined in @file{scm/output-lib.scm},
+where the last three columns indicate whether the layout objects
+will be visible in the positions shown at the head of the columns:
+
+@multitable @columnfractions .40 .15 .15 .15 .15
+@c TODO check these more carefully
+@headitem Function                   @tab Vector                  @tab Before @tab At no    @tab After
+@headitem form                       @tab form                    @tab break  @tab break    @tab break
+
+@item @code{all-invisible}           @tab @code{'#(#f #f #f)} @ @ @tab no     @tab no       @tab no
+@item @code{begin-of-line-visible}   @tab @code{'#(#f #f #t)}     @tab no     @tab no       @tab yes
+@item @code{end-of-line-visible}     @tab @code{'#(#t #f #f)}     @tab yes    @tab no       @tab no
+@item @code{all-visible}             @tab @code{'#(#t #t #t)}     @tab yes    @tab yes      @tab yes
+@c The center-visible function is not defined
+@c @item @code{center-visible}       @tab @code{'#(#f #t #f)}     @tab no     @tab yes      @tab no
+@item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)}     @tab yes    @tab yes      @tab no
+@item @code{end-of-line-invisible}   @tab @code{'#(#f #t #t)}     @tab no     @tab yes      @tab yes
+@item @code{center-invisible}        @tab @code{'#(#t #f #t)}     @tab yes    @tab no       @tab yes
+@end multitable
+
+The @code{center-visible} function is not pre-defined.
+
+The default settings of @code{break-visibility} depend on the
+layout object.  The following table shows all the layout objects
+of interest which are affected by @code{break-visibility} and the
+default setting of this property:
+
+@multitable @columnfractions .3 .3 .4
+
+@headitem Layout object   @tab Usual context  @tab Default setting
+
+@c omit Ambitus as it appears not to be affected by break-visibility -td
+@c @item @code{Ambitus}          @tab as specified   @tab @code{begin-of-line-visible}
+@item @code{BarLine}             @tab @code{Score}          @tab calculated
+@item @code{BarNumber}           @tab @code{Score}          @tab @code{begin-of-line-visible}
+@c omit the following item until it can be explained -td
+@c @item @code{BreakAlignGroup}  @tab @code{Score}          @tab calculated
+@item @code{BreathingSign}       @tab @code{Voice}          @tab @code{begin-of-line-invisible}
+@item @code{Clef}                @tab @code{Staff}          @tab @code{begin-of-line-visible}
+@item @code{Custos}              @tab @code{Staff}          @tab @code{end-of-line-visible}
+@item @code{DoublePercentRepeat} @tab @code{Voice}          @tab @code{begin-of-line-invisible}
+@c omit KeyCancellation until it can be explained -td
+@c @item @code{KeyCancellation}  @tab ??             @tab @code{begin-of-line-invisible}
+@item @code{KeySignature}        @tab @code{Staff}          @tab @code{begin-of-line-visible}
+@c omit LeftEdge until it can be explained -td
+@c @item @code{LeftEdge}         @tab @code{Score}          @tab @code{center-invisible}
+@item @code{OctavateEight}       @tab @code{Staff}          @tab @code{begin-of-line-visible}
+@item @code{RehearsalMark}       @tab @code{Score}          @tab @code{end-of-line-invisible}
+@item @code{TimeSignature}       @tab @code{Staff}          @tab @code{all-visible}
+
+@end multitable
+
+The example below shows the use of the vector form to control the
+visibility of barlines:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+f4 g a b
+f4 g a b
+% Remove bar line at the end of the current line
+\once \override Score.BarLine #'break-visibility = #'#(#f #t #t)
+\break
+f4 g a b
+f4 g a b
+@end lilypond
+
+Although all three components of the vector used to override
+@code{break-visibility} must be present, not all of them are
+effective with every layout object, and some combinations may
+even give errors.  The following limitations apply:
+
+@itemize @bullet
+@item Bar lines cannot be printed at start of line.
+@item A bar number cannot be printed at the start of the first
+line unless it is set to be different from 1.
+@item Clef -- see below
+@item Double percent repeats are either all printed or all
+suppressed.  Use begin-of line-invisible to print and
+all-invisible to suppress.
+@item Key signature -- see below
+@item OctavateEight -- see below
+@end itemize
+
+@node Special considerations
+@unnumberedsubsubsec Special considerations
+
+@strong{@emph{Visibility following explicit changes}}
+
+@cindex key signature, visibility following explicit change
+@cindex explicitKeySignatureVisibility
+@cindex clef, visibility following explicit change
+@cindex explicitClefVisibility
+
+The @code{break-visibility} property controls the visibility of
+key signatures and changes of clef only at the start of lines,
+i.e. after a break.  It has no effect on the visibility of the
+key signature or clef following an explicit key change or an
+explicit clef change within or at the end of a line.  In the
+following example the key signature following the explicit change
+to B-flat major is still visible, even though @code{all-invisible}
+is set.
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+% Try to remove all key signatures
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b
+\break
+f4 g a b
+f4 g a b
+@end lilypond
+
+The visibility of such explicit key signature and clef changes is
+controlled by the @code{explicitKeySignatureVisibility} and
+@code{explicitClefVisibility} properties.  These are the equivalent
+of the @code{break-visibility} property and both take a vector of
+three booleans or the predefined functions listed above, exactly like
+@code{break-visibility}.  Both are properties of the Staff context,
+not the layout objects themselves, and so they are set using the
+@code{\set} command.  Both are set by default to @code{all-visible}.
+These properties control only the visibility of key signatures and
+clefs resulting from explicit changes and do not affect key
+signatures and clefs at the beginning of lines;
+@code{break-visibility} must still be overridden in the appropriate
+object to remove these.
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+@strong{@emph{Visibility of cautionary accidentals}}
+
+To remove the cautionary accidentals printed at an explicit key
+change, set the Staff context property @code{printKeyCancellation}
+to @code{#f}:
+
+@lilypond[quote,verbatim,relative=1,ragged-right]
+\key g \major
+f4 g a b
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\set Staff.printKeyCancellation = ##f
+\override Staff.KeySignature #'break-visibility = #all-invisible
+\key bes \major
+f4 g a b \break
+f4 g a b
+f4 g a b
+@end lilypond
+
+With these overrides only the accidentals before the notes remain
+to indicate the change of key.
+
+@c TODO Add visibility of cautionary accidentals before notes
+
+@strong{@emph{Automatic bars}}
+
+@cindex automaticBars
+@cindex bar lines, suppressing
+
+As a special case, the printing of bar lines can also be turned off
+by setting the @code{automaticBars} property in the Score context.
+If set to @code{#f}, bar lines will not be printed automatically;
+they must be explicitly created with a @code{\bar} command.  Unlike
+the @code{\cadenzaOn} predefined command, measures are still counted.
+Bar generation will resume according to that count if this property
+is later set to @code{#t}.  When set to @code{#f}, line breaks can
+occur only at explicit @code{\bar} commands.
+
+@c TODO Add example
+
+@strong{@emph{Octavated clefs}}
+
+@cindex octavated clefs, visibility of
+@cindex visibility of octavated clefs
+@cindex clefs, visibility of octavation
+
+The small octavation symbol on octavated clefs is produced by the
+@code{OctavateEight} layout object.  Its visibility is controlled
+independently from that of the @code{Clef} object, so it is
+necessary to apply any required @code{break-visibility} overrides
+to both the @code{Clef} and the @code{OctavateEight} layout objects
+to fully suppress such clef symbols at the start of each line.
+
+For explicit clef changes, the @code{explicitClefVisibility}
+property controls both the clef symbol and any octavation symbol
+associated with it.
+
+
+@seealso
+Learning Manual:
+@rlearning{Visibility and color of objects}
+
 
 @node Line styles
 @subsection Line styles
@@ -1773,7 +2122,7 @@ d,2 \glissando d'2
 
 The information that determines the end-points is computed
 on-the-fly for every graphic object, but it is possible to
-override these. 
+override these.
 
 @lilypond[relative=2,ragged-right,verbatim,fragment]
 e2 \glissando f
@@ -1789,14 +2138,14 @@ right end point.  Of course, it is also possible to adjust the
 left side with @code{left} instead of @code{right}.
 
 If @code{Y} is not set, the value is computed from the vertical
-position of right attachment point of the spanner. 
+position of right attachment point of the spanner.
 
 In case of a line break, the values for the span-points are
 extended with contents of the @code{left-broken} and
 @code{right-broken} sublists, for example
 
 @lilypond[relative=2,ragged-right,verbatim,fragment]
-\override Glissando #'breakable = ##T 
+\override Glissando #'breakable = ##T
 \override Glissando #'bound-details #'right-broken #'Y = #-3
 c1 \glissando \break
 f1
@@ -1821,7 +2170,7 @@ head it is attached to.
 
 @item X
 This is the absolute coordinate of the end point.  It is usually
-computed on the fly, and there is little use in overriding it. 
+computed on the fly, and there is little use in overriding it.
 
 @item stencil
 Line spanners may have symbols at the beginning or end, which is
@@ -1913,6 +2262,7 @@ Internals Reference: @rinternals{TextSpanner},
 * Vertical grouping of grobs::
 * Modifying ends of spanners::
 * Modifying stencils::
+* Modifying shapes::
 @end menu
 
 
@@ -1941,6 +2291,11 @@ VerticalAxisGroup.
 
 @c FIXME Write this section
 
+@node Modifying shapes
+@subsection Modifying shapes
+
+@c FIXME Write this section
+@c Discussion of Bezier curves and the control-points property
 
 @node Discussion of specific tweaks
 @section Discussion of specific tweaks
diff --git a/Documentation/user/editorial.itely b/Documentation/user/editorial.itely
index 5eac81eb03..7bdca44e34 100644
--- a/Documentation/user/editorial.itely
+++ b/Documentation/user/editorial.itely
@@ -40,14 +40,32 @@ inside the staff.
 @node Selecting notation font size
 @unnumberedsubsubsec Selecting notation font size
 
+@cindex font size (notation) scaling
 @cindex font size (notation)
 @cindex selecting font size (notation)
+@cindex notation font size
+@cindex note heads
+@funindex fontSize
+@funindex font-size
+@funindex magstep
+@funindex \huge
+@funindex \large
+@funindex \normalsize
+@funindex \small
+@funindex \tiny
+@funindex \teeny
+@funindex huge
+@funindex large
+@funindex normalsize
+@funindex small
+@funindex tiny
+@funindex teeny
 
 The font size of notation elements may be altered.  It does not
 change the size of variable symbols, such as beams or slurs.
 
 @warning{For font sizes of text, see
-@ref{Common markup commands}.}
+@ref{Selecting font and font size}.}
 
 @lilypond[verbatim,quote,relative=2]
 \huge
@@ -64,8 +82,6 @@ c4.-> d8---3
 c4.-> d8---3
 @end lilypond
 
-@cindex font size (notation) scaling
-
 Internally, this sets the @code{fontSize} property.  This in turn
 causes the @code{font-size} property to be set in all layout
 objects.  The value of @code{font-size} is a number indicating the
@@ -89,6 +105,8 @@ c4.-> d8---3
 
 @cindex standard font size (notation)
 @cindex font size (notation), standard
+@funindex font-interface
+@funindex font-size
 
 Font size changes are achieved by scaling the design size that is
 closest to the desired size.  The standard font size (for
@@ -130,6 +148,8 @@ Internals Reference:
 
 @cindex fingering
 @cindex finger change
+@funindex \finger
+@funindex finger
 
 Fingering instructions can be entered using
 @var{note}-@var{digit}:
@@ -145,6 +165,8 @@ c4-1 d-2 f-4 c^\markup { \finger "2 - 3" }
 @end lilypond
 
 @cindex thumb-script
+@funindex \thumb
+@funindex thumb
 
 A thumb-script can be added (e.g., in cello music) to indicate
 that a note should be played with the thumb. 
@@ -154,6 +176,7 @@ that a note should be played with the thumb.
 @end lilypond
 
 @cindex fingering chords
+@cindex fingering instructions for chords
 @cindex chords, fingering
 
 Fingerings for chords can also be added to individual notes of the
@@ -197,8 +220,13 @@ Internals Reference:
 @cindex hidden notes
 @cindex invisible notes
 @cindex transparent notes
+@cindex notes, hidden
+@cindex notes, invisible
+@cindex notes, transparent
 @funindex \hideNotes
+@funindex hideNotes
 @funindex \unHideNotes
+@funindex unHideNotes
 
 Hidden (or invisible or transparent) notes can be useful in
 preparing theory or composition exercises.
@@ -227,8 +255,6 @@ e4(\p f)--
 
 @predefined
 
-@funindex \hideNotes
-@funindex \unHideNotes
 @code{\hideNotes}, @code{\unHideNotes}
 
 @seealso
@@ -250,6 +276,13 @@ Internals Reference:
 @cindex colored notes
 @cindex coloring notes
 @cindex notes, colored
+@cindex x11 color
+@cindex x11-color
+@cindex with-color
+@funindex color
+@funindex \with-color
+@funindex with-color
+@funindex x11-color
 
 Individual objects may be assigned colors.  Valid color names
 are listed in the @ref{List of colors}.
@@ -263,7 +296,6 @@ d
 e
 @end lilypond
 
-@cindex x11-color
 
 The full range of colors defined for X11 can be accessed by using
 the Scheme function @code{x11-color}.  The function takes one
@@ -293,6 +325,11 @@ gis a
 b2 cis
 @end lilypond
 
+@cindex rgb-color
+@cindex color, rgb
+@cindex rgb color
+@funindex rgb-color
+
 Exact RGB colors can be specified using the Scheme function
 @code{rgb-color}.
 
@@ -319,6 +356,12 @@ the input}.
 Snippets:
 @rlsr{Editorial annotations}.
 
+@cindex x11 color
+@cindex colored notes in chords
+@cindex notes, colored in chords
+@cindex color in chords
+@funindex x11-color
+
 @knownissues
 An X11 color is not necessarily exactly the same shade as a
 similarly named normal color.  
@@ -340,6 +383,8 @@ Notes in a chord cannot be colored with @code{\override}; use
 @cindex notes, ghost
 @cindex notes, parenthesized
 @cindex parentheses
+@funindex \parenthesize
+@funindex parenthesize
 
 Objects may be parenthesized by prefixing @code{\parenthesize} to
 the music event.  When prefixed to a chord, it parenthesizes every
@@ -379,6 +424,8 @@ chord.
 @unnumberedsubsubsec Stems
 
 @cindex stem
+@cindex stem, invisible
+@cindex invisible stem
 
 Whenever a note is found, a @code{Stem} object is created
 automatically.  For whole notes and rests, they are also created but
@@ -432,6 +479,16 @@ from outside of the staff.
 @node Balloon help
 @unnumberedsubsubsec Balloon help
 
+@cindex balloon
+@cindex notation, explaining
+@cindex balloon help
+@cindex help, balloon
+@funindex \balloonGrobText
+@funindex \balloonText
+@funindex Balloon_engraver
+@funindex balloonGrobText
+@funindex balloonText
+
 Elements of notation can be marked and named with the help of a
 square balloon.  The primary purpose of this feature is to explain
 notation.
@@ -447,8 +504,6 @@ notation.
 }
 @end lilypond
 
-@cindex balloon
-@cindex notation, explaining
 
 There are two music functions, @code{balloonGrobText} and
 @code{balloonText};  the former is used like
@@ -477,6 +532,9 @@ altered:
 
 @funindex balloonLengthOn
 @funindex balloonLengthOff
+@funindex \balloonLengthOn
+@funindex \balloonLengthOff
+
 @code{\balloonLengthOn}, @code{\balloonLengthOff}
 
 @seealso
@@ -493,6 +551,14 @@ Internals Reference:
 @node Grid lines
 @unnumberedsubsubsec Grid lines
 
+@cindex grid lines
+@cindex lines, grid
+@cindex vertical lines between staves
+@cindex lines, vertical between staves
+@funindex Grid_point_engraver
+@funindex Grid_line_span_engraver
+@funindex gridInterval
+
 Vertical lines can be drawn between staves synchronized with the
 notes.
 
@@ -556,9 +622,17 @@ Internals Reference:
 @unnumberedsubsubsec Analysis brackets
 
 @cindex brackets
-@cindex phrasing brackets
+@cindex bracket, phrasing
+@cindex phrasing bracket
 @cindex musicological analysis
 @cindex note grouping bracket
+@cindex horizontal bracket
+@cindex bracket, horizontal
+@funindex Horizontal_bracket_engraver
+@funindex \startGroup
+@funindex startGroup
+@funindex \stopGroup
+@funindex stopGroup
 
 Brackets are used in musical analysis to indicate structure in musical
 pieces.  Simple horizontal brackets are supported.
diff --git a/Documentation/user/expressive.itely b/Documentation/user/expressive.itely
index 9bb34c806c..e292e5c683 100644
--- a/Documentation/user/expressive.itely
+++ b/Documentation/user/expressive.itely
@@ -147,23 +147,41 @@ Internals Reference:
 @cindex dynamics
 @cindex dynamics, absolute
 @funindex \ppppp
+@funindex ppppp
 @funindex \pppp
+@funindex pppp
 @funindex \ppp
+@funindex ppp
 @funindex \pp
+@funindex pp
 @funindex \p
+@funindex p
 @funindex \mp
+@funindex mp
 @funindex \mf
+@funindex mf
 @funindex \f
+@funindex f
 @funindex \ff
+@funindex ff
 @funindex \fff
+@funindex fff
 @funindex \ffff
+@funindex ffff
 @funindex \fp
+@funindex fp
 @funindex \sf
+@funindex sf
 @funindex \sff
+@funindex sff
 @funindex \sp
+@funindex sp
 @funindex \spp
+@funindex spp
 @funindex \sfz
+@funindex sfz
 @funindex \rfz
+@funindex rfz
 
 Absolute dynamic marks are specified using a command after a note,
 such as @code{c4\ff}.  The available dynamic marks are
@@ -171,7 +189,7 @@ such as @code{c4\ff}.  The available dynamic marks are
 @code{\mp}, @code{\mf}, @code{\f}, @code{\ff}, @code{\fff},
 @code{\ffff}, @code{\fp}, @code{\sf}, @code{\sff}, @code{\sp},
 @code{\spp}, @code{\sfz}, and @code{\rfz}.  The dynamic marks may
-be manually placed above or below the staff, see 
+be manually placed above or below the staff, see
 @ref{Direction and placement}.
 
 @lilypond[verbatim,quote,relative=2]
@@ -181,6 +199,8 @@ c2_\spp c^\ff
 @end lilypond
 
 @cindex hairpin
+@cindex crescendo
+@cindex decrescendo
 @funindex \<
 @funindex \>
 @funindex \!
@@ -208,12 +228,17 @@ c1\!
 
 Spacer rests are needed to engrave multiple marks on one note.
 
+@cindex multiple dynamic marks on one note
+@cindex dynamic marks, multiple on one note
+
 @lilypond[verbatim,quote,relative=2]
 c4\< c\! d\> e\!
 << f1 { s4 s4\< s4\> s4\! } >>
 @end lilypond
 
 @cindex espressivo articulation
+@funindex \espressivo
+@funindex espressivo
 
 In some situations the @code{\espressivo} articulation mark may be
 the appropriate choice to indicate a crescendo and decrescendo on
@@ -227,6 +252,18 @@ g1\espressivo
 @cindex crescendo
 @cindex decrescendo
 @cindex diminuendo
+@funindex \crescTextCresc
+@funindex crescTextCresc
+@funindex \dimTextDecresc
+@funindex dimTextDecresc
+@funindex \dimTextDecr
+@funindex dimTextDecr
+@funindex \dimTextDim
+@funindex dimTextDim
+@funindex \crescHairpin
+@funindex crescHairpin
+@funindex \dimHairpin
+@funindex dimHairpin
 
 Crescendos and decrescendos can be engraved as textual markings
 instead of hairpins.  Dashed lines are printed to indicate their
@@ -247,9 +284,14 @@ c2\< d | e f\!
 e2\> d\!
 @end lilypond
 
+
 To create new absolute dynamic marks or text that should be
 aligned with dynamics, see @ref{New dynamic marks}.
 
+@cindex dynamics, vertical positioning
+@cindex vertical positioning of dynamics
+@funindex DynamicLineSpanner
+
 Vertical positioning of dynamics is handled by
 @rinternals{DynamicLineSpanner}.
 
@@ -257,22 +299,31 @@ Vertical positioning of dynamics is handled by
 @predefined
 
 @funindex \dynamicUp
+@funindex dynamicUp
 @code{\dynamicUp},
 @funindex \dynamicDown
+@funindex dynamicDown
 @code{\dynamicDown},
 @funindex \dynamicNeutral
+@funindex dynamicNeutral
 @code{\dynamicNeutral},
 @funindex \crescTextCresc
+@funindex crescTextCresc
 @code{\crescTextCresc},
 @funindex \dimTextDim
+@funindex dimTextDim
 @code{\dimTextDim},
 @funindex \dimTextDecr
+@funindex dimTextDecr
 @code{\dimTextDecr},
 @funindex \dimTextDecresc
+@funindex dimTextDecresc
 @code{\dimTextDecresc},
 @funindex \crescHairpin
+@funindex crescHairpin
 @code{\crescHairpin},
 @funindex \dimHairpin
+@funindex dimHairpin
 @code{\dimHairpin}.
 
 
@@ -313,7 +364,9 @@ Learning Manual:
 
 Notation Reference:
 @ref{Direction and placement},
-@ref{New dynamic marks}.
+@ref{New dynamic marks},
+@ref{What goes into the MIDI output?},
+@ref{Controlling MIDI dynamics}.
 
 Snippets:
 @rlsr{Expressive marks}.
@@ -344,27 +397,32 @@ moltoF = \markup { molto \dynamic f }
 
 @cindex dynamics, editorial
 @cindex dynamics, parenthesis
+@cindex editorial dynamics
+@funindex \bracket
+@funindex bracket
+@funindex \dynamic
+@funindex dynamic
 
 In markup mode, editorial dynamics (within parentheses or square
 brackets) can be created.  The syntax for markup mode is described
 in @ref{Formatting text}.
 
 @lilypond[verbatim,quote]
-roundf = \markup { \center-align { \line { \bold { \italic ( }
-         \dynamic f \bold { \italic ) } } } }
-boxf = \markup { \bracket { \dynamic f } }
+roundF = \markup { \hcenter \concat { \bold { \italic ( }
+           \dynamic f \bold { \italic ) } } }
+boxF = \markup { \bracket { \dynamic f } }
 \relative c' {
-  c1_\roundf
-  c1_\boxf
+  c1_\roundF
+  c1_\boxF
 }
 @end lilypond
 
-By default, markup objects are aligned to the left side of a note
-head, but authentic dynamic marks are always centered on the note
-head.  New, centered dynamic marks can be created using the
-following function:
-
 @cindex make-dynamic-script
+@funindex make-dynamic-script
+
+Simple, centered dynamic marks are easily created with the
+@code{make-dynamic-script} function.  The dynamic font only
+contains the characters @code{f,m,p,r,s} and @code{z}.
 
 @lilypond[verbatim,quote]
 sfzp = #(make-dynamic-script "sfzp")
@@ -373,33 +431,51 @@ sfzp = #(make-dynamic-script "sfzp")
 }
 @end lilypond
 
-@noindent
-The dynamic font only contains the characters @code{f,m,p,r,s} and
-@code{z}.  In order to use other font families, it is necessary to
-use markup mode in its Scheme form, as explained in
-@ref{Markup construction in Scheme}.
+In general, @code{make-dynamic-script} takes any markup object as
+its argument.  In the following example, using
+@code{make-dynamic-script} ensures the vertical alignment of
+markup objects and hairpins that are attached to the same note
+head.
 
 @lilypond[verbatim,quote]
-moltoF = #(make-dynamic-script (markup 
-                      #:normal-text "molto"
-                      #:dynamic "f"))
+roundF = \markup { \hcenter \concat {
+           \normal-text { \bold { \italic ( } }
+           \dynamic f
+           \normal-text { \bold { \italic ) } } } }
+boxF = \markup { \bracket { \dynamic f } }
+roundFdynamic = #(make-dynamic-script roundF)
+boxFdynamic = #(make-dynamic-script boxF)
+\relative c' {
+  c4_\roundFdynamic\< d e f
+  g,1_\boxFdynamic
+}
+@end lilypond
+
+The Scheme form of markup mode may be used instead.  Its syntax is
+explained in @ref{Markup construction in Scheme}.
+
+@lilypond[verbatim,quote]
+moltoF = #(make-dynamic-script
+            (markup #:normal-text "molto"
+                    #:dynamic "f"))
 \relative c' {
   <d e>16 <d e>
   <d e>2..\moltoF
 }
 @end lilypond
 
-@noindent
 Font settings in markup mode are described in
-@ref{Common markup commands}.
+@ref{Selecting font and font size}.
 
 
 @seealso
 
 Notation Reference:
 @ref{Formatting text},
-@ref{Common markup commands},
-@ref{Markup construction in Scheme}.
+@ref{Selecting font and font size},
+@ref{Markup construction in Scheme},
+@ref{What goes into the MIDI output?},
+@ref{Controlling MIDI dynamics}.
 
 Snippets:
 @rlsr{Expressive marks}.
@@ -432,6 +508,14 @@ a4 g2 f4)
 <c e>2( <b d>2)
 @end lilypond
 
+@cindex slurs, manual placement
+@cindex slurs, below notes
+@cindex slurs, above notes
+@funindex \slurDown
+@funindex slurDown
+@funindex \slurNeutral
+@funindex slurNeutral
+
 Slurs may be manually placed above or below the notes, see
 @ref{Direction and placement}.
 
@@ -443,9 +527,31 @@ c2( d)
 c2( d)
 @end lilypond
 
+@cindex phrasing slur
+@cindex multiple slurs
+@cindex simultaneous slurs
+@cindex slur, phrasing
+@cindex slurs, multiple
+@cindex slurs, simultaneous
+
 Phrasing slurs must be used to print more than one slur at once.
 For details, see @ref{Phrasing slurs}.
 
+@cindex slur style
+@cindex slur, solid
+@cindex slur, dotted
+@cindex slur, dashed
+@cindex solid slur
+@cindex dotted slur
+@cindex dashed slur
+@cindex sytle, slur
+@funindex \slurDashed
+@funindex slurDashed
+@funindex \slurDotted
+@funindex slurDotted
+@funindex \slurSolid
+@funindex slurSolid
+
 Slurs can be solid, dotted, or dashed.  Solid is the default slur
 style:
 
@@ -487,6 +593,9 @@ g4( e c2)
 Music Glossary:
 @rglos{slur}.
 
+Learning Manual:
+@rlearning{On the un-nestedness of brackets and ties}.
+
 Notation Reference:
 @ref{Direction and placement},
 @ref{Phrasing slurs}.
@@ -503,6 +612,8 @@ Internals Reference:
 
 @cindex phrasing slurs
 @cindex phrasing marks
+@cindex slur, phrasing
+@cindex mark, phrasing
 @funindex \(
 @funindex \)
 
@@ -515,6 +626,13 @@ c4\( d( e) f(
 e2) d\)
 @end lilypond
 
+@funindex \phrasingSlurUp
+@funindex phrasingSlurUp
+@funindex \phrasingSlurDown
+@funindex phrasingSlurDown
+@funindex \phrasingSlurNeutral
+@funindex phrasingSlurNeutral
+
 Typographically, a phrasing slur behaves almost exactly like a
 normal slur.  However, they are treated as different objects; a
 @code{\slurUp} will have no effect on a phrasing slur.  Phrasing
@@ -527,21 +645,28 @@ c4\( g' c,( b) | c1\)
 c4\( g' c,( b) | c1\)
 @end lilypond
 
+@cindex simultaneous phrasing slurs
+@cindex multiple phrasing slurs
+@cindex slurs, simultaneous phrasing
+@cindex slurs, multiple phrasing
+@cindex phrasing slurs, simultaneous
+@cindex phrasing slurs, multiple
+
 Simultaneous phrasing slurs are not permitted.
 
 
 @predefined
 
-@funindex \phrasingSlurUp
 @code{\phrasingSlurUp},
-@funindex \phrasingSlurDown
 @code{\phrasingSlurDown},
-@funindex \phrasingSlurNeutral
 @code{\phrasingSlurNeutral}.
 
 
 @seealso
 
+Learning Manual:
+@rlearning{On the un-nestedness of brackets and ties}.
+
 Notation Reference:
 @ref{Direction and placement}.
 
@@ -557,6 +682,7 @@ Internals Reference:
 
 @cindex breath marks
 @funindex \breathe
+@funindex breathe
 
 Breath marks are entered using @code{\breathe}:
 
@@ -599,6 +725,7 @@ Internals Reference:
 @cindex falls
 @cindex doits
 @funindex \bendAfter
+@funindex bendAfter
 
 @notation{Falls} and @notation{doits} can be added to notes using
 the @code{\bendAfter} command.  The direction of the fall or doit
@@ -651,6 +778,7 @@ follow a linear path: glissandos, arpeggios, and trills.
 
 @cindex glissando
 @funindex \glissando
+@funindex glissando
 
 A @notation{glissando} is created by attaching @code{\glissando}
 to a note:
@@ -700,6 +828,14 @@ supported.
 @cindex arpeggio
 @cindex broken chord
 @cindex chord, broken
+@funindex \arpeggio
+@funindex arpeggio
+@funindex \arpeggioArrowUp
+@funindex arpeggioArrowUp
+@funindex \arpeggioArrowDown
+@funindex arpeggioArrowDown
+@funindex \arpeggioNormal
+@funindex arpeggioNormal
 
 An @notation{arpeggio} on a chord (also known as a broken chord)
 is denoted by appending @code{\arpeggio} to the chord construct:
@@ -721,6 +857,13 @@ Different types of arpeggios may be written.
 <c e g c>2\arpeggio
 @end lilypond
 
+@cindex arpeggio symbols, special
+@cindex special arpeggio symbols
+@funindex \arpeggioBracket
+@funindex arpeggioBracket
+@funindex \arpeggioParenthesis
+@funindex arpeggioParenthesis
+
 Special @emph{bracketed} arpeggio symbols can be created:
 
 @lilypond[verbatim,quote,relative=1]
@@ -738,17 +881,11 @@ information, see @ref{Ties}.
 
 @predefined
 
-@funindex \arpeggio
 @code{\arpeggio},
-@funindex \arpeggioArrowUp
 @code{\arpeggioArrowUp},
-@funindex \arpeggioArrowDown
 @code{\arpeggioArrowDown},
-@funindex \arpeggioNormal
 @code{\arpeggioNormal},
-@funindex \arpeggioBracket
 @code{\arpeggioBracket},
-@funindex \arpeggioParenthesis
 @code{\arpeggioParenthesis}.
 
 
@@ -782,6 +919,10 @@ Internals Reference:
 
 @knownissues
 
+@cindex cross-staff parenthesis-style arpeggio
+@cindex arpeggio, parenthesis-style, cross-staff
+@cindex arpeggio, cross-staff parenthesis-style
+
 It is not possible to mix connected arpeggios and unconnected
 arpeggios in one @code{PianoStaff} at the same point in
 time.
@@ -795,15 +936,27 @@ cross-staff arpeggios.
 
 @cindex trills
 @funindex \trill
+@funindex trill
+@funindex \startTrillSpan
+@funindex startTrillSpan
+@funindex \stopTrillSpan
+@funindex stopTrillSpan
 
 Short @notation{trills} without an extender line are printed with
 @code{\trill}; see @ref{Articulations and ornamentations}.
 
 Longer trills with an extender line are made with
-@code{\startTrillSpan} and @code{\stopTrillSpan}.  In the
-following example, the trill is combined with grace notes.  To
-achieve precise control over the placement of the grace notes, see
-@ref{Grace notes}.
+@code{\startTrillSpan} and @code{\stopTrillSpan}:
+
+@lilypond[verbatim,quote,relative=2]
+d1~\startTrillSpan
+d1
+c2\stopTrillSpan r2
+@end lilypond
+
+In the following example, a trill is combined with grace notes.
+The syntax of this construct and the method to precisely position
+the grace notes are described in @ref{Grace notes}.
 
 @lilypond[verbatim,quote,relative=2]
 c1 \afterGrace
@@ -813,24 +966,23 @@ e2 r2
 
 @cindex pitched trills
 @cindex trills, pitched
+@funindex \pitchedTrill
+@funindex pitchedTrill
 
 Trills that require an auxiliary note with an explicit pitch can
 be typeset with the @code{\pitchedTrill} command.  The first
 argument is the main note, and the second is the @emph{trilled}
 note, printed as a stemless note head in parentheses.
 
-@c This syntax example doesn't look nice. -pm
-
-@c @example
-@c @code{\pitchedTrill} @var{mainnote} @code{\startTrillSpan}
-@c @var{trillnote} @var{endnote} @code{\stopTrillSpan}
-@c @end example
-
 @lilypond[verbatim,quote,relative=1]
 \pitchedTrill e2\startTrillSpan fis
 d\stopTrillSpan
 @end lilypond
 
+@cindex pitched trill with forced accidental
+@cindex trill, pitched with forced accidental
+@cindex accidental, forced for pitched trill
+
 In the following example, the second pitched trill is ambiguous;
 the accidental of the trilled note is not printed.  As a
 workaround, the accidentals of the trilled notes can be forced.
@@ -850,9 +1002,7 @@ g\stopTrillSpan
 
 @predefined
 
-@funindex \startTrillSpan
 @code{\startTrillSpan},
-@funindex \stopTrillSpan
 @code{\stopTrillSpan}.
 
 
@@ -870,3 +1020,4 @@ Snippets:
 
 Internals Reference:
 @rinternals{TrillSpanner}.
+
diff --git a/Documentation/user/fretted-strings.itely b/Documentation/user/fretted-strings.itely
index e49b1bc739..335f4e4727 100644
--- a/Documentation/user/fretted-strings.itely
+++ b/Documentation/user/fretted-strings.itely
@@ -36,8 +36,9 @@ to fretted string instruments.
 * String number indications::   
 * Default tablatures::          
 * Custom tablatures::           
-* Automatic fret diagrams::               
 * Fret diagram markups::
+* Predefined fret diagrams::
+* Automatic fret diagrams::               
 * Right-hand fingerings::       
 @end menu
 
@@ -286,115 +287,6 @@ Internals Reference:
 
 No guitar special effects have been implemented.
 
-@node Automatic fret diagrams
-@subsubsection Automatic fret diagrams
-@cindex fret diagrams
-@cindex chord diagrams
-
-Fret diagrams can be automatically created from entered notes using the 
-@code{FretBoards} context.  This context calculates strings and frets
-which can be used to play the notes.
-
-@lilypond[quote,ragged-right,verbatim]
-<<
-  \context ChordNames {
-     \chordmode { 
-       f1 g  
-     }
-  }
-  \context FretBoards {
-    < f, c f a c' f'>1
-    < g,\6 b, d g b g'>
-  }
-  \context Staff {
-    \clef "treble_8"
-    < f, c f a c' f'>1
-    < g, b, d g b' g'>
-  }  
->>
-@end lilypond
-
-Notes can be explicitly placed on a string.  It is often enough
-to place only the lowest note on an explicit string; the rest of 
-the notes will then be placed appropriately by the @code{FretBoards}
-context.
-
-@lilypond[quote,ragged-right,verbatim]
-<<
-  \context ChordNames {
-     \chordmode { 
-       c1 c d:m d:m    
-     }
-  }
-  \context FretBoards {
-    < c e g c' e' > 1
-    < c\5 e g c' e' > 1
-    < d a d' f'>
-    < d\4 a d' f'>
-  }
-  \context Staff {
-    \clef "treble_8"
-    < c e g c' e' > 1
-    < c e g c' e' > 1
-    < d a d' f'>
-    < d a d' f'>
-  }  
->>
-@end lilypond
-
-Fingerings can be added to FretBoard fret diagrams.
-
-@lilypond[quote, verbatim]
-<<
-  \context ChordNames {
-     \chordmode { 
-       c1 d:m          
-     }
-  }
-  \context FretBoards {
-    < c\5-3 e-2 g c'-1 e' > 1
-    < d\4 a-2 d'-3 f'-1>
-  }
-  \context Staff {
-    \clef "treble_8"
-    < c e g c' e' > 1
-    < d a d' f'>
-  }  
->>
-@end lilypond
-
-The strings and frets for the @code{FretBoards} context depend
-on the @code{stringTunings} property, which has the same meaning
-as in the TabStaff context.  See @ref{Custom tablatures} for 
-information on the @code{stringTunings} property. 
-
-The graphical layout of a fret diagram can be customized according to
-user preference through the properties of the @code{fret-diagram-interface}.
-Details are found at @rinternals{fret-diagram-interface}.  For a 
-@code{FretBoards} fret diagram, the interface properties belong to 
-@code{FretBoards}.
-
-@snippets
-The minimum fret to be used in calculating strings and frets for
-the FretBoard context can be set with the @code{minimumFret}
-property.
-
-@c TODO -- snippet showing minimum fret.
-
-@c TODO -- snippet for using StringTunings
-
-@seealso
-
-Notation Reference:
-@ref{Custom tablatures}
-
-Snippets:
-@rlsr{Fretted strings}.
-
-Internals Reference:
-@rinternals {fret-diagram-interface}.
-
-
 @node Fret diagram markups
 @subsubsection Fret diagram markups
 @cindex fret diagrams
@@ -724,6 +616,372 @@ Snippets:
 Internals Reference:
 @rinternals{fret-diagram-interface}.
 
+@node Predefined fret diagrams
+@subsubsection Predefined fret diagrams
+@cindex fret diagrams
+@cindex chord diagrams
+
+Fret diagrams can be displayed using the @code{FretBoards} context.  By
+default, the @code{FretBoards} context will display fret diagrams that
+are stored in a lookup table:
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+\context FretBoards {
+  \chordmode {
+    c1 d
+  }
+}
+@end lilypond
+
+The default predefined fret diagrams are contained in the file
+@code{predefined-guitar-fretboards.ly}.  Fret diagrams are 
+stored based on the pitches of a chord and the value of
+@code{StringTunings} that is currently in use.  
+@code{predefined-guitar-fretboards.ly} contains predefined 
+fret diagrams only for @code{guitar-tuning}.  Predefined fret
+diagrams can be added for other instruments or other tunings
+by following the examples found in 
+@code{predefined-guitar-fretboards.ly}.  
+
+Chord pitches can be entered
+either as simultaneous music or using chord mode (see
+@ref{Chord mode overview}).
+
+@lilypond[verbatim, ragged-right,quote]
+\include "predefined-guitar-fretboards.ly"
+\context FretBoards {
+  \chordmode {c1}
+  <c' e' g'>1
+}
+@end lilypond
+
+It is common that both chord names and fret diagrams are displayed together.
+This is achieved by putting a @code{ChordNames} context in parallel with
+a @code{FretBoards} context and giving both contexts the same music.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+mychords = \chordmode{
+  c1 f g
+}
+
+<<
+  \context ChordNames {
+    \mychords
+  }
+  \context FretBoards {
+    \mychords
+  }
+>>
+@end lilypond
+
+Predefined fret diagrams are transposable, as long as a diagram for the
+transposed chord is stored in the fret diagram table.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+mychords = \chordmode{
+  c1 f g
+}
+
+mychordlist = {
+  \mychords
+  \transpose c e { \mychords}
+}
+<<
+  \context ChordNames {
+    \mychordlist
+  }
+  \context FretBoards {
+    \mychordlist
+  }
+>>
+@end lilypond
+
+
+The predefined fret diagram table contains seven chords (major, minor,
+augmented, diminished, dominant seventh, major seventh, minor seventh)
+for each of 17 keys.  A complete list of the predefined fret diagrams is
+shown in @ref{Predefined fretboard diagrams}.  If there is no entry in
+the table for a chord, the FretBoards engraver will calculate a
+fret-diagram using the automatic fret diagram functionality described in
+@ref{Automatic fret diagrams}.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+mychords = \chordmode{
+  c1 c:9
+}
+
+<<
+  \context ChordNames {
+    \mychords
+  }
+  \context FretBoards {
+    \mychords
+  }
+>>
+@end lilypond
+
+Fret diagrams can be added to the fret diagram table.  To add a diagram,
+you must specify the chord for the diagram, the tuning to be used, and the
+fret-diagram-terse definition string for the diagram.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+
+\storePredefinedDiagram \chordmode {c:9} 
+                        #guitar-tuning
+                        #"x;3-2;2-1;3-3;3-4;x;"
+
+mychords = \chordmode{
+  c1 c:9
+}
+
+<<
+  \context ChordNames {
+    \mychords
+  }
+  \context FretBoards {
+    \mychords
+  }
+>>
+@end lilypond
+
+Different fret diagrams for the same chord name can be stored using different
+octaves of pitches.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+
+\storePredefinedDiagram \chordmode {c'} 
+                        #guitar-tuning
+                        #(offset-fret 2 (chord-shape 'bes))
+
+mychords = \chordmode{
+  c1 c'
+}
+
+<<
+  \context ChordNames {
+    \mychords
+  }
+  \context FretBoards {
+    \mychords
+  }
+>>
+@end lilypond
+
+In addition to fret diagrams, LilyPond stores an internal list of chord
+shapes.  The chord shapes are fret diagrams that can be shifted along
+the neck to different posistions to provide different chords.  Chord
+shapes can be added to the internal list and then used to define
+predefined fret diagrams.
+
+@lilypond[verbatim, ragged-right, quote]
+\include "predefined-guitar-fretboards.ly"
+
+% add a new chord shape
+
+\addChordShape #'powerf #"1-1;3-3;3-4;x;x;x;"
+
+% add some new chords based on the power chord shape
+
+\storePredefinedDiagram \chordmode {f'} 
+                        #guitar-tuning 
+                        #(chord-shape 'powerf)
+\storePredefinedDiagram \chordmode {g'} 
+                        #guitar-tuning
+                        #(offset-fret 2 (chord-shape 'powerf))
+
+mychords = \chordmode{
+  f1 f' g g' 
+}
+
+<<
+  \context ChordNames {
+    \mychords
+  }
+  \context FretBoards {
+    \mychords
+  }
+>>
+@end lilypond
+
+The graphical layout of a fret diagram can be customized according to
+user preference through the properties of the @code{fret-diagram-interface}.
+Details are found at @rinternals{fret-diagram-interface}.  For a 
+predefined fret diagram, the interface properties belong to @code{FretBoards}.
+
+@c @snippets
+
+@seealso
+
+Notation Reference:
+@ref{Custom tablatures},
+@ref{Automatic fret diagrams},
+@ref{Chord mode overview},
+@ref{Predefined fretboard diagrams}.
+
+Installed Files:
+@file{ly/predefined-guitar-fretboards.ly}.
+
+Snippets:
+@rlsr{Fretted strings}.
+
+Internals Reference:
+@rinternals {fret-diagram-interface}.
+
+
+@node Automatic fret diagrams
+@subsubsection Automatic fret diagrams
+@cindex fret diagrams
+@cindex chord diagrams
+
+Fret diagrams can be automatically created from entered notes using the 
+@code{FretBoards} context.  If no predefined diagram is available for
+the entered notes in the active @code{stringTunings}, this context
+calculates strings and frets that can be used to play the notes.
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+  \context ChordNames {
+     \chordmode { 
+       f1 g  
+     }
+  }
+  \context FretBoards {
+    < f, c f a c' f'>1
+    < g,\6 b, d g b g'>
+  }
+  \context Staff {
+    \clef "treble_8"
+    < f, c f a c' f'>1
+    < g, b, d g b' g'>
+  }  
+>>
+@end lilypond
+
+As no predefined diagrams are loaded by default, automatic calculation 
+of fret diagrams is the default behavior.  Once default diagrams are
+loaded, automatic calculation can be enabled and disabled with predefined
+commands:
+
+@lilypond[quote,ragged-right,verbatim]
+
+\storePredefinedDiagram <c\5 e g c' e'>
+                        #guitar-tuning
+                        #"x;3-1-(;5-2;5-3;5-4;3-1-1);"
+<<
+  \context ChordNames {
+     \chordmode { 
+       c1 c c 
+     }
+  }
+  \context FretBoards {
+    <c\5 e g c' e'>1
+    \predefinedFretboardsOff
+    <c\5 e g c' e'>
+    \predefinedFretboardsOn
+    <c\5 e g c' e'>
+  }
+  \context Staff {
+    \clef "treble_8"
+    <c\5 e g c' e'>1
+    <c\5 e g c' e'>
+    <c\5 e g c' e'>
+  }  
+>>
+@end lilypond
+
+  
+
+Notes can be explicitly placed on a string.  It is often enough
+to place only the lowest note on an explicit string; the rest of 
+the notes will then be placed appropriately by the @code{FretBoards}
+context.
+
+@lilypond[quote,ragged-right,verbatim]
+<<
+  \context ChordNames {
+     \chordmode { 
+       c1 c d:m d:m    
+     }
+  }
+  \context FretBoards {
+    < c e g c' e' > 1
+    < c\5 e g c' e' > 1
+    < d a d' f'>
+    < d\4 a d' f'>
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c e g c' e' > 1
+    < c e g c' e' > 1
+    < d a d' f'>
+    < d a d' f'>
+  }  
+>>
+@end lilypond
+
+Fingerings can be added to FretBoard fret diagrams.
+
+@lilypond[quote, verbatim]
+<<
+  \context ChordNames {
+     \chordmode { 
+       c1 d:m          
+     }
+  }
+  \context FretBoards {
+    < c\5-3 e-2 g c'-1 e' > 1
+    < d\4 a-2 d'-3 f'-1>
+  }
+  \context Staff {
+    \clef "treble_8"
+    < c e g c' e' > 1
+    < d a d' f'>
+  }  
+>>
+@end lilypond
+
+The strings and frets for the @code{FretBoards} context depend
+on the @code{stringTunings} property, which has the same meaning
+as in the TabStaff context.  See @ref{Custom tablatures} for 
+information on the @code{stringTunings} property. 
+
+The graphical layout of a fret diagram can be customized according to
+user preference through the properties of the @code{fret-diagram-interface}.
+Details are found at @rinternals{fret-diagram-interface}.  For a 
+@code{FretBoards} fret diagram, the interface properties belong to 
+@code{FretBoards}.
+
+@snippets
+The minimum fret to be used in calculating strings and frets for
+the FretBoard context can be set with the @code{minimumFret}
+property.
+
+@c TODO -- snippet showing minimum fret.
+
+@c TODO -- snippet for using StringTunings
+
+@predefined
+\predefinedFretboardsOff,
+\predefinedFretboardsOn.
+
+@seealso
+
+Notation Reference:
+@ref{Custom tablatures}.
+
+Snippets:
+@rlsr{Fretted strings}.
+
+Internals Reference:
+@rinternals {fret-diagram-interface}.
+
+
 @node Right-hand fingerings
 @subsubsection Right-hand fingerings
 
diff --git a/Documentation/user/introduction.itely b/Documentation/user/introduction.itely
index 5875d37673..32e425a216 100644
--- a/Documentation/user/introduction.itely
+++ b/Documentation/user/introduction.itely
@@ -789,6 +789,7 @@ makes it easy to mix music and text in documents.
 This section explains the different portions of the documentation.
 
 @c leave these lines wrapping around.  It's some texinfo 4.12 thing. -gp
+@c This is actually a limitation of texi2html. -jm
 @menu
 * About the Learning Manual (LM)::  this manual introduces LilyPond, giving in-depth explanations of how to create notation.
 
@@ -950,7 +951,7 @@ a complete index.
 @node About the Application Usage (AU)
 @unnumberedsubsec About the Application Usage (AU)
 
-This book explains how to execute the program and how to integrate
+This book explains how to execute the programs and how to integrate
 LilyPond notation with other programs.
 
 @itemize
diff --git a/Documentation/user/keyboards.itely b/Documentation/user/keyboards.itely
index 6064369ad9..e1db372244 100644
--- a/Documentation/user/keyboards.itely
+++ b/Documentation/user/keyboards.itely
@@ -39,6 +39,14 @@ instruments.
 @node References for keyboards
 @unnumberedsubsubsec References for keyboards
 
+@cindex piano staves
+@cindex staves, piano
+@cindex staves, keyboard instruments
+@cindex staves, keyed instruments
+@cindex keyboard instrument staves
+@cindex keyed instrument staves
+@funindex PianoStaff
+
 Keyboard instruments are usually notated with Piano staves.  These
 are two or more normal staves coupled with a brace.  The same
 notation is also used for other keyed instruments.
@@ -53,6 +61,7 @@ music.
 Several common issues in keyboard music are covered elsewhere:
 
 @itemize
+
 @item Keyboard music usually contains multiple voices and the
 number of voices may change regularly; this is described in
 @ref{Collision resolution}.
@@ -110,6 +119,12 @@ Snippets:
 
 @knownissues
 
+@cindex keyboard music, centering dynamics
+@cindex dynamics, centered in keyboard music
+@cindex piano music, centering dynamics
+@cindex centered dynamics in piano music
+@funindex staff-padding
+
 Dynamics are not automatically centered, but workarounds do exist.  One
 option is the @q{piano centered dynamics} template under
 @rlearning{Piano templates}; another option is to increase the
@@ -127,6 +142,7 @@ objects}.
 @cindex cross-staff beams
 @cindex beams, cross-staff
 @funindex \change
+@funindex change
 
 Voices can be switched between staves manually, using the command
 
@@ -192,6 +208,8 @@ Internals Reference:
 @cindex automatic staff changes
 @cindex staff changes, automatic
 @funindex \autochange
+@funindex autochange
+@funindex PianoStaff
 
 Voices can be made to switch automatically between the top and the
 bottom staff.  The syntax for this is
@@ -217,6 +235,11 @@ in advance.
 }
 @end lilypond
 
+@cindex relative music and autochange
+@cindex autochange and relative music
+@funindex \relative
+@funindex relative
+
 A @code{\relative} section that is outside of @code{\autochange}
 has no effect on the pitches of the music, so if necessary, put
 @code{\relative} inside @code{\autochange}.
@@ -258,6 +281,8 @@ Internals Reference:
 
 @knownissues
 
+@cindex chords, splitting across staves with \autochange
+
 The staff switches may not end up in optimal places.  For high
 quality output, staff switches should be specified manually.
 
@@ -267,13 +292,21 @@ staff based on the first note named in the chord construct.
 @node Staff-change lines
 @unnumberedsubsubsec Staff-change lines
 
-@cindex staff-change lines
-@cindex cross-staff lines
-@cindex lines, staff-change follower
+@cindex staff-change line
+@cindex staff change line
+@cindex cross-staff line
+@cindex cross staff line
+@cindex line, staff-change follower
+@cindex line, cross-staff
+@cindex line, staff-change
 @cindex follow voice
 @cindex staff switching
 @cindex cross-staff
 @funindex followVoice
+@funindex \showStaffSwitch
+@funindex showStaffSwitch
+@funindex \hideStaffSwitch
+@funindex hideStaffSwitch
 
 Whenever a voice switches to another staff, a line connecting the
 notes can be printed automatically:
@@ -295,8 +328,6 @@ notes can be printed automatically:
 
 @predefined
 
-@funindex \showStaffSwitch
-@funindex \hideStaffSwitch
 @code{\showStaffSwitch}, @code{\hideStaffSwitch}.
 
 @seealso
@@ -313,9 +344,18 @@ Internals Reference:
 @unnumberedsubsubsec Cross-staff stems
 
 @cindex cross-staff notes
+@cindex cross staff notes
 @cindex notes, cross-staff
 @cindex cross-staff stems
+@cindex cross staff stems
 @cindex stems, cross-staff
+@cindex chords, cross-staff
+@cindex cross-staff chords
+@cindex cross staff chords
+@funindex Stem
+@funindex cross-staff
+@funindex length
+@funindex flag-style
 
 Chords that cross staves may be produced:
 
@@ -371,18 +411,27 @@ piano.
 
 @node Piano pedals
 @unnumberedsubsubsec Piano pedals
+
 @cindex piano pedals
 @cindex pedals, piano
 @cindex sustain pedal
 @cindex sostenuto pedal
 @cindex una corda
 @cindex tre corde
+@cindex sos.
+@cindex U.C.
 @funindex \sustainOn
+@funindex sustainOn
 @funindex \sustainOff
+@funindex sustainOff
 @funindex \sostenutoOn
+@funindex sostenutoOn
 @funindex \sostenutoOff
+@funindex sostenutoOff
 @funindex \unaCorda
+@funindex unaCorda
 @funindex \treCorde
+@funindex treCorde
 
 Pianos generally have three pedals that alter the way sound is
 produced: @notation{sustain}, @notation{sostenuto}
@@ -398,6 +447,17 @@ c4\unaCorda d e g
 <d fis a>1\treCorde
 @end lilypond
 
+@cindex pedal indication styles
+@cindex pedal indication, text
+@cindex pedal indication, bracket
+@cindex pedal indication, mixed
+@cindex pedal sustain style
+@cindex sustain pedal style
+@funindex pedalSustainStyle
+@funindex mixed
+@funindex bracket
+@funindex text
+
 There are three styles of pedal indications: text, bracket, and mixed.
 The sustain pedal and the una corda pedal use the text style by default
 while the sostenuto pedal uses mixed by default.
@@ -441,6 +501,8 @@ Internals Reference:
 @node Accordion
 @subsection Accordion
 
+@cindex accordion
+
 This section discusses notation that is unique to the accordion.
 
 @menu
@@ -452,6 +514,7 @@ This section discusses notation that is unique to the accordion.
 @cindex accordion discant symbols
 @cindex discant symbols, accordion
 @cindex accordion shifts
+@cindex accordion shift symbols
 
 Accordions are often built with more than one set of reeds that may be
 in unison with, an octave above, or an octave below the written pitch.
diff --git a/Documentation/user/notation-appendices.itely b/Documentation/user/notation-appendices.itely
index b47dd2ece6..3996570429 100644
--- a/Documentation/user/notation-appendices.itely
+++ b/Documentation/user/notation-appendices.itely
@@ -15,6 +15,7 @@
 @menu
 * Chord name chart::            
 * Common chord modifiers::
+* Predefined fretboard diagrams::
 * MIDI instruments::            
 * List of colors::              
 * The Feta font::               
@@ -371,6 +372,13 @@ TODO
 
 @end multitable
 
+@node Predefined fretboard diagrams
+@appendixsec Predefined fretboard diagrams
+
+The chart below shows the predefined fretboard diagrams.
+
+@lilypondfile{display-predefined-fretboards.ly}
+
 @node MIDI instruments
 @appendixsec MIDI instruments
 
diff --git a/Documentation/user/percussion.itely b/Documentation/user/percussion.itely
index afed901cc9..049411d20a 100644
--- a/Documentation/user/percussion.itely
+++ b/Documentation/user/percussion.itely
@@ -60,19 +60,107 @@ context and entry mode for percussion:
 }
 @end lilypond
 
-This is shorthand for
+This is shorthand for:
 
 @lilypond[quote,ragged-right,verbatim]
-\new DrumStaff
-\drummode {
-  hihat hh bassdrum bd
+\new DrumStaff {
+  \drummode {
+    hihat hh bassdrum bd
+  }
 }
 @end lilypond
 
+Note, that percussion clefs are added automatically in a
+@code{DrumStaff} context.  But it is possible to use other clefs
+if you want.
+
 
 The complete list of drum names is in the init file
 @file{ly/@/drumpitch@/-init@/.ly}.
-@c TODO: properly document this.
+
+Here is the list of abbreviations You can use in a drum Staff:
+
+@example
+   bda  acousticbassdrum
+   bd  bassdrum
+   ssh  hisidestick
+   ss  sidestick
+   ssl  losidestick
+   sna  acousticsnare
+   sn  snare
+   hc  handclap
+   sne  electricsnare
+   tomfl  lowfloortom
+   hhc  closedhihat
+   hh  hihat
+   tomfh  highfloortom
+   hhp  pedalhihat
+   toml  lowtom
+   hho  openhihat
+   hhho  halfopenhihat
+   tomml  lowmidtom
+   tommh  himidtom
+   cymca  crashcymbala
+   cymc  crashcymbal
+   tomh  hightom
+   cymra  ridecymbala
+   cymr  ridecymbal
+   cymch  chinesecymbal
+   rb  ridebell
+   tamb  tambourine
+   cyms  splashcymbal
+   cb  cowbell
+   cymcb  crashcymbalb
+   vibs  vibraslap
+   cymrb  ridecymbalb
+   bohm  mutehibongo
+   boh  hibongo
+   boho  openhibongo
+   bolm  mutelobongo
+   bol  lobongo
+   bolo  openlobongo
+   cghm  mutehiconga
+   cglm  muteloconga
+   cgho  openhiconga
+   cgh  hiconga
+   cglo  openloconga
+   cgl  loconga
+   timh  hitimbale
+   timl  lotimbale
+   agh  hiagogo
+   agl  loagogo
+   cab  cabasa
+   mar  maracas
+   whs  shortwhistle
+   whl  longwhistle
+   guis  shortguiro
+   guil  longguiro
+   gui  guiro
+   cl  claves
+   wbh  hiwoodblock
+   wbl  lowoodblock
+   cuim  mutecuica
+   cuio  opencuica
+   trim  mutetriangle
+   tri  triangle
+   trio  opentriangle
+   tt  tamtam
+   ua  oneup
+   ub  twoup
+   uc  threeup
+   ud  fourup
+   ue  fiveup
+   da  onedown
+   db  twodown
+   dc  threedown
+   dd  fourdown
+   de  fivedown
+@end example
+
+Note that the normal notation of pitches in a @code{DrumStaff}
+will cause an error message.
+
+
 
 Drum rolls are indicated with three slashes across the stem.
 For quarter notes or longer the three slashes are shown explicitly,
@@ -97,7 +185,13 @@ Sticking can be indicated by placing @code{^"R"} or @code{^"L"}
 after the note.  The @code{staff-padding} property may be
 overridden to achieve a pleasing baseline.
 
-@c TODO Add example of sticking
+@lilypond[quote,ragged-right,verbatim]
+\drums {
+	\repeat "unfold" 2 { sn16 ^"L" sn^"R" sn^"L" sn^"L" sn^"R" sn^"L"  sn^"R" sn^"R" }
+				
+}
+@end lilypond
+
 
 @seealso
 
diff --git a/Documentation/user/spacing.itely b/Documentation/user/spacing.itely
index 5bc88ae90f..5d8dd6ec00 100644
--- a/Documentation/user/spacing.itely
+++ b/Documentation/user/spacing.itely
@@ -1606,8 +1606,7 @@ Proportional notation is supported; see @ref{Proportional notation}.
 @seealso
 
 Internals: @rinternals{SpacingSpanner}, @rinternals{NoteSpacing},
-@rinternals{StaffSpacing}, @rinternals{SeparationItem}, and
-@rinternals{SeparatingGroupSpanner}.
+@rinternals{StaffSpacing}, and @rinternals{SeparationItem}.
 
 
 @knownissues
diff --git a/Documentation/user/staff.itely b/Documentation/user/staff.itely
index d025bda0d8..3c4be6a41d 100644
--- a/Documentation/user/staff.itely
+++ b/Documentation/user/staff.itely
@@ -18,23 +18,23 @@ scores with more than one staff, and how to apply specific
 performance marks to single staves.
 
 @menu
-* Displaying staves::           
-* Modifying single staves::     
-* Writing parts::               
+* Displaying staves::
+* Modifying single staves::
+* Writing parts::
 @end menu
 
 
 @node Displaying staves
 @subsection Displaying staves
 
-This section shows the different possibilities to create and group
-staves into groups, which can be marked in the beginning of each
-line with either a bracket or a brace.
+This section shows the different possibilities of creating and
+grouping staves, which are marked at the beginning of each line
+with either a bracket or a brace.
 
 @menu
 * Instantiating new staves::
-* Grouping staves:: 
-* Deeper nested staff groups::  
+* Grouping staves::
+* Deeper nested staff groups::
 @end menu
 
 @node Instantiating new staves
@@ -52,71 +52,57 @@ line with either a bracket or a brace.
 @cindex tabstaff
 @cindex tablature
 
-Staves (sg. staff) are created with the @code{\new} or
-@code{\context} commands.  For an explanation on these commands,
-see @ref{Creating contexts}.
+@notation{Staves} (singular: @notation{staff}) are created with
+the @code{\new} or @code{\context} commands.  For details, see
+@ref{Creating contexts}.
 
-There are different predefined staff contexts available in
-LilyPond:
-
-@itemize
-@item
-The default is @code{Staff}:
+The basic staff context is @code{Staff}:
 
 @lilypond[verbatim,quote,relative=2]
 \new Staff { c4 d e f }
 @end lilypond
 
-@item
-@code{DrumStaff} creates a five line staff set up for a typical
-drum set.  It uses different names for each instrument.  The
-instrument names have to be set using the @code{drummode}.  See
-@ref{Percussion staves}.
+@code{DrumStaff} creates a five-line staff set up for a
+typical drum set.  It uses different names for each instrument.
+The instrument names are set using the @code{\drummode} command.
+For details, see @ref{Percussion staves}.
 
 @lilypond[verbatim,quote]
-\new DrumStaff { 
+\new DrumStaff {
   \drummode { cymc hh ss tomh }
 }
 @end lilypond
 
 @c FIXME: remove when mentioned in NR 2.8
-@item
-@code{GregorianTranscriptionStaff} sets up a staff to notate
+@code{GregorianTranscriptionStaff} creates a staff to notate
 modern Gregorian chant.  It does not show bar lines.
 
 @lilypond[verbatim,quote,relative=2]
 \new GregorianTranscriptionStaff { c4 d e f }
 @end lilypond
 
-@item
-@code{RhythmicStaff} can be used to show the rhythm of some music.
-The notes are printed on one line regardless of their pitch, but
-the duration is preserved.  See @ref{Showing melody rhythms}.
+@code{RhythmicStaff} creates a single-line staff that only
+displays the rhythmic values of the input.  Real durations are
+preserved. For details, see @ref{Showing melody rhythms}.
 
 @lilypond[verbatim,quote,relative=2]
 \new RhythmicStaff { c4 d e f }
 @end lilypond
 
-@item
-@code{TabStaff} creates by default a tablature with six strings in
-standard guitar tuning.  See @ref{Default tablatures}.
+@code{TabStaff} creates a tablature with six strings in standard
+guitar tuning.  For details, see @ref{Default tablatures}.
 
 @lilypond[verbatim,quote,relative=2]
 \new TabStaff { c4 d e f }
 @end lilypond
 
-@end itemize
+There are two staff contexts specific for the notation of ancient
+music: @code{MensuralStaff} and @code{VaticanaStaff}.  They are
+described in @ref{Pre-defined contexts}.
 
-@noindent
-Besides these staves there are two staff contexts specific for the
-notation of ancient music: @code{MensuralStaff} and
-@code{VaticanaStaff}.  They are described in @ref{Pre-defined
-contexts}.
-
-Once a staff is instantiated it can be started or stopped at every
-point in the score.  This is done with the commands
-@code{\startStaff} and @code{\stopStaff}.  How to use it is
-explained in @ref{Staff symbol}.
+Staves can be started or stopped at any point in the score.  The
+commands @code{\startStaff} and @code{\stopStaff} are used for
+this purpose.  For details, see @ref{Staff symbol}.
 
 
 @seealso
@@ -127,7 +113,7 @@ Music Glossary:
 
 Notation Reference:
 @ref{Creating contexts},
-@ref{Percussion staves}, 
+@ref{Percussion staves},
 @ref{Default tablatures},
 @ref{Gregorian chant contexts},
 @ref{Mensural contexts},
@@ -158,24 +144,21 @@ Internals Reference:
 @cindex system start delimiters
 @cindex bracket, vertical
 @cindex brace, vertical
+@cindex choir staff
 @cindex grand staff
 @cindex piano staff
 @cindex staff group
 @cindex staff, choir
-@cindex choir staff
+@cindex staff, piano
 @cindex system
 
-LilyPond provides different types of contexts to group single
-staves together.  These contexts influence in the first place the
-appearance of the system start delimiter, but they have also
-influence on the behavior of the bar lines.
+Various contexts exist to group single staves together in order to
+form multi-stave systems.  Each grouping context sets the style of
+the system start delimiter and the behavior of bar lines.
 
-@itemize
-@item
-If no context is specified, the default properties for the score
-will be used: the group is started with a vertical line, and the
-bar lines are not connected.  The name of the beginning bar line
-grob is @code{SystemStartBar}.  
+If no context is specified, the default properties will be used:
+the group is started with a vertical line, and the bar lines are
+not connected.
 
 @lilypond[verbatim,quote,relative=2]
 <<
@@ -184,9 +167,8 @@ grob is @code{SystemStartBar}.
 >>
 @end lilypond
 
-@item
-In a @code{StaffGroup}, the bar lines will be drawn through all
-the staves, and the group is started with a bracket.
+In the @code{StaffGroup} context, the group is started with a
+bracket and bar lines are drawn through all the staves.
 
 @lilypond[verbatim,quote,relative=2]
 \new StaffGroup <<
@@ -195,9 +177,8 @@ the staves, and the group is started with a bracket.
 >>
 @end lilypond
 
-@item
-In a @code{ChoirStaff}, the group is started with a bracket, but
-bar lines are not connected. 
+In a @code{ChoirStaff}, the group starts with a bracket, but bar
+lines are not connected.
 
 @lilypond[verbatim,quote,relative=2]
 \new ChoirStaff <<
@@ -206,9 +187,8 @@ bar lines are not connected.
 >>
 @end lilypond
 
-@item
-In a @code{GrandStaff}, the group is started with a brace at the
-left, and bar lines are connected between the staves. 
+In a @code{GrandStaff}, the group begins with a brace, and bar
+lines are connected between the staves.
 
 @lilypond[verbatim,quote,relative=2]
 \new GrandStaff <<
@@ -217,42 +197,24 @@ left, and bar lines are connected between the staves.
 >>
 @end lilypond
 
-@item
-The @code{PianoStaff} behaves almost as the @code{GrandStaff} but
-is optimized for setting piano music. In particular it supports
-the printing of an instrument name directly, see @ref{Instrument
-names}.
+The @code{PianoStaff} is almost identical to a @code{GrandStaff},
+except that it supports printing the instrument name directly.
+For details, see @ref{Instrument names}.
 
 @lilypond[verbatim,quote,relative=2]
 \new PianoStaff <<
+  \set PianoStaff.instrumentName = "Piano"
   \new Staff { c1 c }
   \new Staff { c1 c }
 >>
 @end lilypond
 
-@end itemize
-
 Each staff group context sets the property
-@code{systemStartDelimiter} to one of the values
-@code{SystemStartBar}, @code{SystemStartBrace}, and
+@code{systemStartDelimiter} to one of the following values:
+@code{SystemStartBar}, @code{SystemStartBrace}, or
 @code{SystemStartBracket}.  A fourth delimiter,
-@code{systemStartSquare}, is also available, but must be
-instantiated manually.  The usage of this last delimiter is shown
-further down in the snippet section.
-
-According to classic engraver rules an orchestral score consists
-of staves connected only with a single line at the beginning of
-the system.  In LilyPond this is produced grouping the
-@code{Staff} contexts with @code{<< ... >>}.
-
-Each instrument family is grouped inside of a @code{StaffGroup}
-with a starting bracket.  A group of same instruments or an
-instrument using more than one staff is grouped with braces in a
-@code{GrandStaff}.
-
-As the context names tell, @code{PianoStaff} is used for notating
-piano music and @code{ChoirStaff} for all kind of vocal ensemble
-music.
+@code{SystemStartSquare}, is also available, but it must be
+explicitly specified.
 
 
 @snippets
@@ -276,7 +238,7 @@ music.
 @seealso
 
 Music Glossary:
-@rglos{brace}, 
+@rglos{brace},
 @rglos{bracket},
 @rglos{grand staff}.
 
@@ -290,33 +252,17 @@ Internals Reference:
 @rinternals{Staff},
 @rinternals{ChoirStaff},
 @rinternals{GrandStaff},
-@rinternals{PianoStaff}, 
+@rinternals{PianoStaff},
 @rinternals{StaffGroup},
-@rinternals{systemStartDelimiter},
 @rinternals{SystemStartBar},
 @rinternals{SystemStartBrace},
 @rinternals{SystemStartBracket},
-@rinternals{systemStartSquare}.
+@rinternals{SystemStartSquare}.
 
 
 @node Deeper nested staff groups
 @unnumberedsubsubsec Deeper nested staff groups
 
-There are also two inner staff contexts named
-@code{InnerStaffGroup} and @code{InnerChoirStaffGroup} besides the
-grouping contexts mentioned in @ref{Grouping staves}.  They behave
-in the same way as their simple counterparts, except that they are
-contained in another staff grouping context, thus producing one
-more bracket on top of the existing one.  Note that
-@code{GrandStaff} and @code{PianoStaff} do not have any inner
-grouping contexts.  They can both be inside any other staff
-context, including inner staff groups, though.
-
-Here is an example of an orchestral score using groupings and
-nesting of these groupings.  Note that the instrument names are
-omitted from the source code, for instructions how to set them see
-@ref{Instrument names}.
-
 @cindex staff, nested
 @cindex staves, nested
 @cindex nesting of staves
@@ -327,85 +273,38 @@ omitted from the source code, for instructions how to set them see
 @cindex inner staff group
 @cindex inner choir staff group
 
-@example
-\score @{
-\relative c' <<
-  \new StaffGroup %woodwinds
-  <<
-  \new Staff @{ c1 d @} %flute
-  \new InnerStaffGroup <<
-    \new Staff @{ c1 d @} %sax 
-    \new Staff @{ c1 d @} %oboe
-    \new Staff @{ c1 d @} %English horn
-    >>
-  \new Staff @{ \clef bass c,1 d @} %bassoon
-  >>
-  \new StaffGroup %the brass group
-  <<
-    \new Staff @{ c'1 d @} %trumpet
-    \new Staff @{ \clef bass c,1 d @} %trombone
-    \new GrandStaff %the horns need a GrandStaff (same instrument)
-    <<
-      \new Staff @{ c'1 d @}
-      \new Staff @{ \clef bass c,1 d @}
-    >>
-  >>
-  \new ChoirStaff %for setting vocal music
-  <<
-   \new Staff @{ c'1 d @}
-    \new InnerChoirStaff <<
-     \new Staff @{ c1 d @}
-     \new Staff @{ c1 d @}
-    >>
-   \new Staff @{ c1 d @}
-  >>
-  \new PianoStaff %for the piano
-  <<
-    \new Staff @{ c1 d @}
-    \new Staff @{ \clef bass c,1 d @}
-  >>
->> @}
-@end example
+Two additional staff-group contexts are available that can be
+nested within a @code{StaffGroup} or @code{ChoirStaff} context:
+@code{InnerStaffGroup} and @code{InnerChoirStaff}.  These contexts
+create an additional bracket next to the original bracket of their
+parent staff group.
 
-@c no verbatim so instrument names are only in the music
-@lilypond[quote]
-\score {
-\relative c' <<
-  \new StaffGroup %woodwinds
-  <<
-  \new Staff { \set Staff.instrumentName = "fl" c1 d } %flute
+An @code{InnerStaffGroup} is treated similarly to a
+@code{StaffGroup}; bar lines are connected between each stave
+within the context:
+
+@lilypond[verbatim,quote,relative=2]
+\new StaffGroup <<
+  \new Staff { c2 c }
   \new InnerStaffGroup <<
-    \new Staff { \set Staff.instrumentName = "sax" c1 d } %sax 1
-    \new Staff { \set Staff.instrumentName = "ob" c1 d } %sax 2
-    \new Staff { \set Staff.instrumentName = "ca" c1 d }
-    >>
-  \new Staff { \set Staff.instrumentName = "bs" \clef bass c,1 d } %bassoon
-  >>
-  \new StaffGroup %the brass group
-  <<
-    \new Staff { \set Staff.instrumentName = "tr" c'1 d } %trumpet
-    \new Staff { \set Staff.instrumentName = "tb" \clef bass c,1 d } %trombone
-    \new GrandStaff %the horns need a GrandStaff (same instrument)
-    <<
-      \new Staff { \set Staff.instrumentName = "cor1" c'1 d }
-      \new Staff { \set Staff.instrumentName = "cor2" \clef bass c,1 d }
-    >>
+    \new Staff { g2 g }
+    \new Staff { e2 e }
   >>
-  \new ChoirStaff %for setting vocal music
-  <<
-   \new Staff { \set Staff.instrumentName = "S" c'1 d }
-    \new InnerChoirStaff <<
-     \new Staff { \set Staff.instrumentName = "A1" c1 d }
-     \new Staff { \set Staff.instrumentName = "A2" c1 d }
-    >>
-   \new Staff { \set Staff.instrumentName = "T" c1 d }
-  >>
-  \new PianoStaff %for the piano
-  <<
-    \new Staff { c1 d }
-    \new Staff { \clef bass c,1 d }
+>>
+@end lilypond
+
+Bar lines are @emph{not} connected between staves of an
+@code{InnerChoirStaff}, just like a @code{ChoirStaff}:
+
+@lilypond[verbatim,quote,relative=2]
+\new ChoirStaff <<
+  \new Staff { c2 c }
+  \new InnerChoirStaff <<
+    \new Staff { g2 g }
+    \new Staff { e2 e }
   >>
->> }
+  \new Staff { c1 }
+>>
 @end lilypond
 
 
@@ -425,27 +324,30 @@ Notation Reference:
 @ref{Instrument names}.
 
 Internals Reference:
-@rinternals{InnerChoirStaffGroup}, 
 @rinternals{InnerStaffGroup},
-@rinternals{SystemStartBar}, 
+@rinternals{StaffGroup},
+@rinternals{InnerChoirStaff},
+@rinternals{ChoirStaff},
+@rinternals{SystemStartBar},
 @rinternals{SystemStartBrace},
-@rinternals{SystemStartBracket},
-@rinternals{systemStartDelimiterHierarchy}.
+@rinternals{SystemStartBracket}.
 
 
 @node Modifying single staves
 @subsection Modifying single staves
 
 This section explains how to change specific attributes of one
-staff like the staff lines, starting and stopping of staves,
-sizing of staves, and setting ossia sections.
+staff: for example, modifying the number of staff lines or the
+staff size.  Methods to start and stop staves and set ossia
+sections are also described.
 
 @menu
-* Staff symbol::   
-* Ossia staves::             
-* Hiding staves::    
+* Staff symbol::
+* Ossia staves::
+* Hiding staves::
 @end menu
 
+
 @node Staff symbol
 @unnumberedsubsubsec Staff symbol
 
@@ -464,17 +366,16 @@ sizing of staves, and setting ossia sections.
 @cindex spacing of ledger lines
 @cindex number of staff lines
 
-The layout object which draws the lines of a staff is called
-@code{staff symbol}.  The staff symbol may be tuned in number,
-thickness and distance of lines, using properties.  It may also be
-started and stopped at every point in the score.
+The grob @code{StaffSymbol} is responsible for drawing the lines
+of a staff.  Its properties can be altered in order to change the
+appearance of a staff, but they must be changed before the staff
+is created.  A staff may be started or stopped at any point in the
+score.
 
-@itemize
-@item
-Changing the number of staff lines is done by overriding
-@code{line-count}.  You may need to adjust the clef position and
-the position of the middle C to fit to the new staff.  For an
-explanation, see the snippet section in @ref{Displaying pitches}.
+The number of staff lines may be changed.  The clef position and
+the position of middle C may need to be modified to fit the new
+staff.  For an explanation, refer to the snippet section in
+@ref{Clef}.
 
 @lilypond[verbatim,quote,relative=2]
 \new Staff {
@@ -483,14 +384,16 @@ explanation, see the snippet section in @ref{Displaying pitches}.
 }
 @end lilypond
 
-@item
-The placement and amount of the staff lines can also set totally
-manually by defining their positions explicitly.  The middle of
-the staff has the value of 0, each half staff space up and down
-adds an integer.  The default values are 4 2 0 -2 -4.  Bar lines
-are drawn according to the calculated width of the system, but
-they are always centered.  As the example shows, the positions of
-the notes are not influenced by the position of the staff lines.
+The vertical position of staff lines and the number of staff lines
+can be defined at the same time.  As the example shows, the
+positions of the notes are not influenced by the position of the
+staff lines.  Details for modifying this property are found in
+@rinternals{staff-symbol-interface}.
+
+@warning{The @code{'line-positions} property overrides the
+@code{'line-count} property.  The number of staff lines is
+implicitly defined by the number of elements in the list of values
+for @code{'line-positions}}
 
 @lilypond[verbatim,quote,relative=1]
 \new Staff \with {
@@ -499,44 +402,30 @@ the notes are not influenced by the position of the staff lines.
 { a4 e' f b | d1 }
 @end lilypond
 
-@item
-The staff line thickness can be set by overriding the
-@code{thickness} property.  Note that it gets applied also to
-ledger lines and stems, since they depend on the staff line
-thickness.  The argument of @code{thickness} is a factor of
-@code{line-thickness} which defaults to the normal staff line
+The staff line thickness can be modified.  The thickness of ledger
+lines and stems are also affected, since they depend on staff line
 thickness.
 
 @lilypond[verbatim,quote,relative=1]
 \new Staff \with {
   \override StaffSymbol #'thickness = #3
 }
-{ d4 d d d }
+{ e4 d c b }
 @end lilypond
 
-@item
-The thickness of the ledger lines can also be set independent of
-the settings for staff lines.  The setting is calculated from a
-pair of values which will be added for the final thickness.  The
-first value is the staff line thickness multiplied by a factor,
-the second is the staff space multiplied by a factor.  In the
-example the ledger lines get their thickness from one staff line
-thickness plus 1/5 staff space, so they are heavier than a normal
-staff line.
+The thickness of ledger lines can be set independently of staff
+line thickness.  A description of this property is also found in
+@rinternals{staff-symbol-interface}.
 
 @lilypond[verbatim,quote,relative=1]
 \new Staff \with {
   \override StaffSymbol #'ledger-line-thickness = #'(1 . 0.2)
 }
-{ d4 d d d }
+{ e4 d c b }
 @end lilypond
 
-@item
-The distance of the stafflines can be changed with the
-@code{staff-space} property. Its argument is the amount of staff
-spaces that should be inserted between the lines.  The default
-value is 1. Setting the distance has influence on the staff lines
-as well as on ledger lines.
+The distance between staff lines can be changed.  The setting has
+influence on ledger lines as well.
 
 @lilypond[verbatim,quote,relative=1]
 \new Staff \with {
@@ -545,10 +434,9 @@ as well as on ledger lines.
 { a4 b c d }
 @end lilypond
 
-@item
-The length of the staff line can also be adjusted manually.  The
-unit is one staff space.  Spacing of the objects inside the staff
-does not get influenced by this setting.
+The width of a staff can be adjusted.  The unit is one staff
+space.  The spacing of objects inside the staff is not influenced
+by this setting.
 
 @lilypond[verbatim,quote,relative=1]
 \new Staff \with {
@@ -557,25 +445,21 @@ does not get influenced by this setting.
 { a4 e' f b | d1 }
 @end lilypond
 
-@end itemize
-
-These properties can only be set before instantiating the staff
-symbol.  But it is possible to start and stop staves in the middle
-of a score, so each new setting will be applied to the newly
-instantiated staff.
+Modifications to staff properties in the middle of a score can be
+placed between @code{\stopStaff} and @code{\startStaff}:
 
 @lilypond[verbatim,quote,relative=2]
-b4 b
-%Set here the overrides for the staff 
-\override Staff.StaffSymbol #'line-count = 2
-\stopStaff \startStaff
-b b
-%Revert to the default
+c2 c
+\stopStaff
+\override Staff.StaffSymbol #'line-count = #2
+\startStaff
+b2 b
+\stopStaff
 \revert Staff.StaffSymbol #'line-count
-\stopStaff \startStaff
-b b
+\startStaff
+a2 a
 @end lilypond
- 
+
 
 @predefined
 
@@ -590,6 +474,7 @@ b b
 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
 {making-some-staff-lines-thicker-than-the-others.ly}
 
+
 @seealso
 
 Music Glossary:
@@ -601,7 +486,9 @@ Notation Reference:
 @ref{Displaying pitches}.
 
 Internals Reference:
-@rinternals{StaffSymbol}.
+@rinternals{StaffSymbol},
+@rinternals{staff-symbol-interface}.
+
 
 @knownissues
 
@@ -633,7 +520,6 @@ Tweaking the staff object allows to resize the staff:
 }
 @end lilypond
 
-@noindent
 This involves shrinking the staff spaces, the staff lines and the
 font size by the factor 3.  You find a more precise explanation in
 @ref{Setting the staff size}.
@@ -666,7 +552,7 @@ space is inserted with the @code{\skip} command.
     s2
 
     \startStaff
-    f8 d g4 
+    f8 d g4
   }
   \new Staff \relative c'' {
     \time 2/4
@@ -678,9 +564,8 @@ space is inserted with the @code{\skip} command.
 
 @snippets
 
-@c @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
-@c {making-some-staff-lines-thicker-than-the-others.ly}
-@c snippet 277
+@lilypondfile[verbatim,lilyquote,texidoc,doctitle]
+{vertically-aligning-ossias-and-lyrics.ly}
 
 
 @seealso
@@ -690,6 +575,11 @@ Music Glossary:
 @rglos{staff},
 @rglos{Frenched staff}.
 
+Learning Manual:
+@rlearning{Nesting music expressions},
+@rlearning{Size of objects},
+@rlearning{Length and thickness of objects}.
+
 Notation Reference:
 @ref{Setting the staff size}.
 
@@ -705,7 +595,7 @@ Internals Reference:
 
 @cindex Frenched scores
 @cindex staff, hiding
-@cindex staff, empty 
+@cindex staff, empty
 @cindex hiding of staves
 @cindex empty staves
 @cindex Frenched staves
@@ -732,7 +622,7 @@ whole mesure rests are removed after a line break.
   <<
     \new Staff { e4 f g a \break c1 }
     \new Staff { c4 d e f \break R1 }
-  >>  
+  >>
 }
 @end lilypond
 
@@ -742,10 +632,15 @@ To remove other types of contexts, use
 
 @cindex ossia
 
+@c FIXME Really? I need to see about this.  -pm
+
 Another application of the @code{\RemoveEmptyStaffContext} is to
 make ossia sections, i.e., alternative melodies on a separate
 piece of staff, with help of a Frenched staff.  See
-@ref{Ossia staves}. 
+@ref{Ossia staves}.
+
+@c FIXME Is this in the right section?
+@c maybe move to Staff symbol -pm
 
 You can make the staff lines invisible by removing the
 @code{Staff_symbol_engraver} from the @code{Staff} context.
@@ -778,15 +673,15 @@ is written.
 
 @lilypond[verbatim,quote]
 \layout {
-  \context { 
-    \RemoveEmptyStaffContext 
+  \context {
+    \RemoveEmptyStaffContext
     %To use the setting globally, uncomment the following line:
     %\override VerticalAxisGroup #'remove-first = ##t
   }
 }
 \new StaffGroup
   \relative c'' <<
-    \new Staff {    
+    \new Staff {
       e4 f g a \break c1 }
     \new Staff {
       %To use the setting globally, comment this line, uncomment the line above
@@ -835,17 +730,17 @@ Internals Reference:
 @subsection Writing parts
 
 @menu
-* Metronome marks::             
-* Instrument names::            
-* Quoting other voices::        
-* Formatting cue notes::        
+* Metronome marks::
+* Instrument names::
+* Quoting other voices::
+* Formatting cue notes::
 @end menu
 
 
 @node Metronome marks
 @unnumberedsubsubsec Metronome marks
 
-@cindex Tempo
+@cindex tempo
 @cindex beats per minute
 @cindex metronome marking
 
@@ -882,7 +777,6 @@ c4^\markup {
   ) }
 @end lilypond
 
-@noindent
 For more details, see @ref{Formatting text}.
 
 
@@ -895,14 +789,14 @@ Music Glossary:
 @rglos{metronome mark}.
 
 Notation Reference:
-@ref{Formatting text}.
+@ref{Formatting text},
+@ref{MIDI output}.
 
 Snippets:
 @rlsr{Staff notation}.
 
 Internals Reference:
-@rinternals{MetronomeMark},
-@ref{MIDI output}.
+@rinternals{MetronomeMark}.
 
 
 @knownissues
@@ -945,8 +839,8 @@ c1
 c''1
 @end lilypond
 
-You can also use markup texts to construct more complicated
-instrument names, for example
+Markup mode can be used to create more complicated instrument
+names:
 
 @lilypond[verbatim,quote,relative=2]
 \set Staff.instrumentName = \markup {
@@ -1000,7 +894,7 @@ in @ref{Modifying context plug-ins}.
 
 @cindex instrument names, changing
 
-Instrument names may be changed in the middle of a piece,
+Instrument names may be changed in the middle of a piece:
 
 @lilypond[verbatim,quote,relative=1]
 \set Staff.instrumentName = "First"
@@ -1161,7 +1055,7 @@ written entirely in lower-case letters: @code{\addquote}.
 @cindex cue notes
 @cindex cue notes, formatting
 @cindex fragments
-@cindex quoting other voices 
+@cindex quoting other voices
 @cindex cues, formatting
 
 The previous section deals with inserting notes from another
diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely
index b1b4a12f03..43f4e94227 100644
--- a/Documentation/user/text.itely
+++ b/Documentation/user/text.itely
@@ -180,8 +180,13 @@ Internals Reference: @rinternals{TextSpanner}.
 Various text elements can be added to a score using
 the syntax described in @ref{Rehearsal marks}:
 
+@c \mark needs to be placed on a separate line (it's not
+@c attached to an object like \markup is). -vv
+
 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
-c4\mark "Allegro" c c c
+c4
+\mark "Allegro"
+c c c
 @end lilypond
 
 This syntax makes it possible to put any text on a bar line;
@@ -191,7 +196,8 @@ signs like coda, segno or fermata, by specifying the appropriate
 symbol name:
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
-c1 \mark \markup { \musicglyph #"scripts.ufermata" }
+c1
+\mark \markup { \musicglyph #"scripts.ufermata" }
 c1
 @end lilypond
 
@@ -203,9 +209,10 @@ beginning of a score or at a line break, marks will be printed at
 the beginning of the line (the next line, in case of a line break).
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
-\mark "Allegro" c1
-c\mark "assai" \break
-c c
+\mark "Allegro"
+c1 c
+\mark "assai" \break
+c  c
 @end lilypond
 
 
@@ -314,7 +321,7 @@ using the @code{\markup} mode specific syntax.
 
 @menu
 * Text markup introduction::    
-* Common markup commands::      
+* Selecting font and font size::      
 * Text alignment::              
 * Graphic notation inside markup::  
 * Music notation inside markup::  
@@ -362,9 +369,9 @@ c
 @cindex quoted text in markup mode
 
 A @code{\markup} block may also contain quoted text, which
-can be useful to print special characters (such as @code{\} and @code{#}).
-Quoted text even allows to print double quotation marks, by preceding
-them with backslashes:
+can be useful to print special characters such as @code{\} and @code{#},
+or even double quotation marks -- these have to be preceded
+with backslashes:
 
 @lilypond[quote,verbatim,fragment,relative=1]
 \clef bass
@@ -385,9 +392,9 @@ c1^\markup { \line { a b c } }
 @end lilypond
 
 Lists of words that are not enclosed with double quotes
-or preceded by a command are not kept distinct.  In
-the following example, the first two @code{\markup} expressions
-are equivalent:
+or preceded by a command are not treated as a distinct
+expression.  In the following example, the first two
+@code{\markup} expressions are equivalent:
 
 @lilypond[quote,verbatim,fragment,relative=1]
 c1^\markup { \center-align { a bbb c } }
@@ -428,20 +435,18 @@ Init files: @file{scm/@/new@/-markup@/.scm}.
 
 @knownissues
 
-Syntax errors for markup mode are confusing.
-
+Syntax errors for markup mode can be confusing.
 
-@node Common markup commands
-@subsubsection Common markup commands
 
-Markup text may be formatted in different ways.
+@node Selecting font and font size
+@subsubsection Selecting font and font size
 
 @cindex font switching
 @funindex \italic
 @funindex \bold
 @funindex \underline
 
-Basic font switching is supported:
+Basic font switching is supported in markup mode:
 
 @lilypond[quote,verbatim,relative=2]
 {
@@ -472,7 +477,7 @@ the font size can be defined to an absolute value,
 predefined commands allow to easily select standard sizes,
 
 @item
-other commands allow to change the size relatively to its previous value.
+the font size can also be changed relatively to its previous value.
 @end itemize
 
 @noindent
@@ -513,10 +518,13 @@ these are printed in a smaller size, but a normal size can be used as well:
 }
 @end lilypond
 
+@cindex font families
+
 The markup mode provides an easy way to select alternate
-font families.  The default serif font, of roman type, is automatically
-selected unless specified otherwise: on the last line of the following example,
-there is no difference between the first word and the following words.
+font families.  The default serif font, of roman type, is
+automatically selected unless specified otherwise: on the
+last line of the following example, there is no difference
+between the first and the second word.
 
 @lilypond[quote,verbatim]
 \markup {
@@ -524,7 +532,7 @@ there is no difference between the first word and the following words.
     \line { Act \number 1 }
     \line { \sans { Scene I. } }
     \line { \typewriter { Verona. An open place. } }
-    \line { \roman Enter Valentine and Proteus. }
+    \line { Enter \roman Valentine and Proteus. }
   }
 }
 @end lilypond
@@ -535,11 +543,34 @@ such as numbers or dynamics, do not provide all
 characters, as mentioned in @ref{New dynamic marks} and
 @ref{Manual repeat marks}.
 
+@c \concat is actually documented in Align (it is not
+@c a font-switching command). But we need it here. -vv
 
-Defining custom font sets is also possible, as explained in
-@ref{Fonts}.  An exhaustive list of font-switching, font-size
+When used inside a word, some font-switching or formatting
+commands may produce an unwanted blank space.  This can
+easily be solved by concatenating the text elements together:
+
+@lilypond[quote,verbatim]
+\markup {
+  \column {
+    \line {
+      \concat { 1 \super st }
+      movement
+    }
+    \line {
+      \concat { \dynamic p , }
+      \italic { con dolce espressione }
+    }
+  }
+}
+@end lilypond
+
+An exhaustive list of font-switching, font-size
 and font-families related commands can be found in @ref{Font}.
 
+Defining custom font sets is also possible, as explained in
+@ref{Fonts}.
+
 @predefined
 
 @funindex \teeny
@@ -555,131 +586,209 @@ and font-families related commands can be found in @ref{Font}.
 @code{\large},
 @code{\huge}.
 
-
 @c TODO: add @seealso
 
-@knownissues
-When used inside a word, some of these commands may produce an unwanted
-blank space.  This can easily be solved by concatenating the text
-elements together, using a specific command
-described in @ref{Text alignment}.
-
-
 
 @node Text alignment
 @subsubsection Text alignment
 
-@warning{This subsection discusses how to place text in markup mode,
-inside a @code{\markup} block.  However, markup objects can also
-be moved as a whole using the syntax described in
-@rlearning{Moving objects}.}
+@cindex text, aligning
+@cindex aligning text
+
+This subsection discusses how to place text in markup mode,
+inside a @code{\markup} block.  Markup objects can also
+be moved as a whole, using the syntax described in
+@rlearning{Moving objects}.
+
+@c The padding commands should be mentioned on this page, but
+@c most of these require \box to be more clearly illustrated. -vv
 
-Markup objects can be aligned in different ways.  By default,
+@cindex text, horizontal alignment
+@cindex horizontal text alignment
+@funindex \left-align
+@funindex \hcenter
+@funindex \right-align
+
+Markup objects may be aligned in different ways.  By default,
 a text indication is aligned on its left edge: in the following
-example, there's no difference between the first and the second
-markup.
+example, there's no difference
+between the first and the second markup.
 
 @lilypond[quote,verbatim,fragment,relative=1]
 a1-\markup { poco }
 e'
 a,-\markup { \left-align poco }
 e'
-a,-\markup { \center-align { poco } }
+a,-\markup { \hcenter { poco } }
 e'
 a,-\markup { \right-align poco }
 @end lilypond
 
-@c FIXME: \center-align actually doesn't belong here
-@c \center-align vs \column
-@c \center-align vs \hcenter
-
-Horizontal alignment:
-\hcenter
-\general-align
-\halign 
-
-
-\null
-\hspace
+@funindex \halign
 
-\lower
-\raise 
-\translate 
-\translate-scaled
-\rotate
-\transparent
-\whiteout
-
-Vertical alignment: 
-\vcenter
-\column 
-\dir-column 
-
-Building a "large" markup:
-
-\line
-
-\fill-line
-
-\hcenter-in
-	
-\pad-around
-\pad-markup
-\pad-to-box
-\pad-x
-	
-Alignment inside a "large" markup:
-
-\justify-field 
-\justify
-\justify-string
-
-\wordwrap-field
-\wordwrap
-\wordwrap-string
+The horizontal alignment may be fine-tuned
+using a numeric value:
 
+@lilypond[quote,verbatim,fragment,relative=1]
+a1-\markup { \halign #-1 poco }
+e'
+a,-\markup { \halign #0 poco }
+e'
+a,-\markup { \halign #0.5 poco }
+e'
+a,-\markup { \halign #2 poco }
+@end lilypond
 
-@ignore
-TODO: here are some commands that could be described here.
-I'm putting them in bulk, prior to working on this section. -vv
+@noindent
+Some objects may have alignment procedures of their own,
+and therefore are not affected by these commands.  It is
+possible to move such markup objects as a whole, as shown
+for instance in @ref{Text marks},
+
+@cindex text, vertical alignment
+@cindex vertical text alignment
+@funindex \raise
+@funindex \lower
+
+Vertical alignment is a bit more complex. As stated above,
+markup objects can be moved as a whole; however, it is also
+possible to move specific elements inside a markup block.
+In this case, the element to be moved needs to be preceded
+with an @emph{anchor point}, that can be another markup element
+or an invisible object.  The following example demonstrates these
+two possibilities; the last markup in this example has no anchor
+point, and therefore is not moved.
 
-\simple
+@lilypond[quote,verbatim,fragment,relative=1]
+d2^\markup { 
+  Acte I
+  \raise #2 { Scène 1 } }
+a'
+g_\markup {
+  \null
+  \lower #4 \bold { Très modéré } }
+a
+d,^\markup {
+  \raise #4 \italic { Une forêt. } }
+a'4 a g2 a
+@end lilypond
 
-\char
-\fraction
+@funindex \general-align
+@funindex \translate
+@funindex \translate-scaled
 
-\combine
-\concat
-\put-adjacent
+Some commands can affect both the horizontal and vertical
+alignment of text objects in markup mode.  Any object
+affected by these commands must be preceded with an
+anchor point:
 
+@lilypond[quote,verbatim,fragment,relative=1]
+d2^\markup {
+  Acte I
+  \translate #'(-1 . 2) "Scène 1" }
+a'
+g_\markup {
+  \null
+  \general-align #Y #3.2 \bold "Très modéré" }
+a
+d,^\markup {
+  \null
+  \translate-scaled #'(-1 . 2) \teeny "Une forêt." }
+a'4 a g2 a
+@end lilypond
 
-\page-ref (see also "Table of contents")
-\fromproperty
-\verbatim-file
-\with-url
+@cindex multi-line markup
+@cindex multi-line text
+@cindex columns, text
 
-\on-the-fly 
-\override
+A markup object may include several lines of text.
+In the following example, each element or expression
+is placed on its own line, either left-aligned or centered:
 
+@lilypond[quote,verbatim]
+\markup {
+  \column {
+    a
+    "b c"
+    \line { d e f }
+  }
+  \hspace #10
+  \center-align {
+    a
+    "b c"
+    \line { d e f }
+  }
+}
+@end lilypond
 
+Similarly, a list of elements or expressions may be
+spread to fill the entire horizontal line width -- if there
+is only one element, it will be centered on the page.
+These expressions can, in turn, include multi-line text
+or any other markup expression:
 
-@end ignore
+@lilypond[quote,verbatim]
+\markup {
+  \fill-line {
+    \line { William S. Gilbert }
+    \center-align {
+      \huge \smallCaps "The Mikado"
+      or
+      \smallCaps "The Town of Titipu"
+    }
+    \line { Sir Arthur Sullivan }
+  }
+}
+\markup {
+  \fill-line { 1885 } 
+}
+@end lilypond
 
+Long text indications can also be automatically wrapped
+accordingly to the given line width.  These will be
+either left-aligned or justified, as shown in
+the following example.
 
-Some objects have alignment procedures of their own, which cancel
-out any effects of alignments applied to their markup arguments as
-a whole.  For example, the @rinternals{RehearsalMark} is
-horizontally centered, so using @code{\mark \markup @{ \left-align
-.. @}} has no effect.
+@lilypond[quote,verbatim]
+\markup {
+  \column {
+    \line  \smallCaps { La vida breve }
+    \line \bold { Acto I }
+    \wordwrap \italic {
+      (La escena representa el corral de una casa de
+      gitanos en el Albaicín de Granada. Al fondo una
+      puerta por la que se vé el negro interior de
+      una Fragua, iluminado por los rojos resplandores
+      del fuego.) 
+    }
+    \hspace #0
+
+    \line \bold { Acto II }
+    \override #'(line-width . 50)
+    \justify \italic {
+      (Calle de Granada. Fachada de la casa de Carmela
+      y su hermano Manuel con grandes ventanas abiertas
+      a través de las que se ve el patio
+      donde se celebra una alegre fiesta)
+    }
+  }
+}
+@end lilypond
 
+An exhaustive list of text alignment commands
+can be found in @ref{Align}.
 
+@c TODO: add @seealso
 
 @node Graphic notation inside markup
 @subsubsection Graphic notation inside markup
+
 Graphics around text:
 \box
 \circle
 
+(TODO: document padding commands here)
+
 \bracket
 \hbracket
 
diff --git a/Documentation/user/tutorial.itely b/Documentation/user/tutorial.itely
index 4e1d289d40..f31c98af41 100644
--- a/Documentation/user/tutorial.itely
+++ b/Documentation/user/tutorial.itely
@@ -1500,7 +1500,7 @@ example from Handel's @notation{Judas Maccabæus}:
 @end lilypond
 
 Scores any more complex than this simple example are better
-produced by separating out the staff structure from the notes and
+produced by separating out the score structure from the notes and
 lyrics with variables.  These are discussed in @ref{Organizing
 pieces with variables}.
 
@@ -1625,7 +1625,7 @@ By convention, this is placed 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}, and it uses @code{\version} to
+program, @command{convert-ly}, and it uses @code{\version} to
 determine what rules to apply.  For details, see
 @rprogram{Updating files with convert-ly}.
 
@@ -1636,7 +1636,7 @@ determine what rules to apply.  For details, see
 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}.
+underneath the version number.
 
 @example
 \version @w{"@version{}"}
diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely
index 8d8925bd89..e59614f71a 100644
--- a/Documentation/user/tweaks.itely
+++ b/Documentation/user/tweaks.itely
@@ -1006,8 +1006,8 @@ We see from the properties specified in the @code{grob-interface}
 page in the IR that the @code{transparent} property is a boolean.
 This
 should be set to @code{#t} to make the grob transparent.
-In this next example let us make the time signature invisible 
-rather than the bar lines.  
+In this next example let us make the time signature invisible
+rather than the bar lines.
 To do this we need to find the grob name for the time signature.
 Back to
 the @q{All layout objects} page in the IR to find the properties
@@ -1028,10 +1028,10 @@ transparent is:
 @end lilypond
 
 @noindent
-The time signature is gone, but this command leaves a gap where 
+The time signature is gone, but this command leaves a gap where
 the time signature should be.  Maybe this is what is wanted for
-an exercise for the student to fill it in, but in other 
-circumstances a gap might be undesirable.  To remove it, the 
+an exercise for the student to fill it in, but in other
+circumstances a gap might be undesirable.  To remove it, the
 stencil for the time signature should be set to @code{#f}
 instead:
 
@@ -1053,8 +1053,16 @@ leaves it where it is, but makes it invisible.
 @subheading color
 @cindex color property
 
-Finally we could make the bar lines invisible by coloring
-them white.  The @code{grob-interface} specifies that the
+Finally let us try making the bar lines invisible by coloring
+them white.  (There is a difficulty with this in that the
+white bar line may or may not blank out the staff lines where
+they cross.  You may see in some of the examples below that this
+happens unpredictably.  The details of why this is so and how to
+control it are covered in @ruser{Painting objects white}.  But at
+the moment we are learning about color, so please just accept this
+limitation for now.)
+
+The @code{grob-interface} specifies that the
 color property value is a list, but there is no
 explanation of what that list should be.  The list it
 requires is actually a list of values in internal units,
@@ -1080,7 +1088,7 @@ and again, we see the bar lines are not visible.  Note that
 a symbol, but a @emph{function}.  When called, it provides
 the list of internal values required to set the color to
 white.  The other colors in the normal list are functions
-too.  To convince yourself this is working you might like 
+too.  To convince yourself this is working you might like
 to change the color to one of the other functions in the
 list.
 
@@ -1113,7 +1121,7 @@ an apostrophe and the two enclosed in brackets.
 
 There is yet a third function, one which converts RGB values into
 internal colors -- the @code{rgb-color} function.  This takes
-three arguments giving the intensities of the red, green and 
+three arguments giving the intensities of the red, green and
 blue colors.  These take values in the range 0 to 1.  So to
 set the color to red the value should be @code{(rgb-color 1 0 0)}
 and to white it should be @code{(rgb-color 1 1 1)}:
diff --git a/GNUmakefile.in b/GNUmakefile.in
index 0cd13623ca..5160939baa 100644
--- a/GNUmakefile.in
+++ b/GNUmakefile.in
@@ -204,7 +204,7 @@ RESULT_DIR=$(top-build-dir)/out/test-results
 
 test:
 	@echo -en 'For tracking crashes: use\n\n\t'
-	@echo 'grep sourcefilename `grep -L systems.texi input/regression/out-test/*log|sed s/log/ly/g`'
+	@echo 'grep sourcefilename `grep -L systems.texi out/lybook-db/*/*log|sed s/log/ly/g`'
 	@echo
 	$(MAKE) -C input/regression/ out=test local-test
 	$(MAKE) -C input/regression/musicxml out=test local-test
diff --git a/input/manual/display-predefined-fretboards.ly b/input/manual/display-predefined-fretboards.ly
new file mode 100644
index 0000000000..a53fb372b4
--- /dev/null
+++ b/input/manual/display-predefined-fretboards.ly
@@ -0,0 +1,67 @@
+\include "predefined-guitar-fretboards.ly"
+
+mychords = \chordmode {c1 c:m c:aug c:dim c:7 c:maj7 c:m7 \break }
+
+chordsline = {
+  \mychords
+  \transpose c cis {
+    \mychords
+  }
+  \transpose c des {
+    \mychords
+  }
+  \transpose c d {
+    \mychords
+  }
+  \transpose c dis {
+    \mychords
+  }
+ \transpose c ees {
+    \mychords
+  }
+  \transpose c e {
+    \mychords
+  }
+  \transpose c f {
+    \mychords
+  }
+  \transpose c fis {
+    \mychords
+  }
+  \transpose c ges {
+    \mychords
+  }
+  \transpose c g {
+    \mychords
+  }
+  \transpose c gis {
+    \mychords
+  }
+  \transpose c aes {
+    \mychords
+  }
+  \transpose c a {
+    \mychords
+  }
+  \transpose c ais {
+    \mychords
+  }
+  \transpose c bes {
+    \mychords
+  }
+  \transpose c b {
+    \mychords
+  }
+}
+
+<<
+  \context ChordNames {
+    \chordsline
+  }
+  \context FretBoards {
+    \chordsline
+  }
+  \context Staff {
+    \chordsline
+  }
+>>
diff --git a/input/regression/dot-rest-beam-trigger.ly b/input/regression/dot-rest-beam-trigger.ly
new file mode 100644
index 0000000000..3714cf7a82
--- /dev/null
+++ b/input/regression/dot-rest-beam-trigger.ly
@@ -0,0 +1,19 @@
+\header {
+
+  texidoc = "Dotted rests connected with beams do not trigger
+  premature beam calculations.  In this case, the beam should be
+  sloped, and there should be no programming_error() warnings."
+
+}
+
+\version "2.11.54"
+\new Staff \relative c''
+{
+  <<
+    { \time 12/16 c16[ b a r  b g] }
+    \\
+    { r8. r }
+  >>
+}
+
+
diff --git a/input/regression/predefined-fretboards.ly b/input/regression/predefined-fretboards.ly
new file mode 100644
index 0000000000..daa88bd03f
--- /dev/null
+++ b/input/regression/predefined-fretboards.ly
@@ -0,0 +1,33 @@
+% add a chord shape
+
+\addChordShape #'bes #"x;1-1-(;3-2;3-3;3-4;1-1-);"
+
+% add chords
+
+\storePredefinedDiagram \chordmode {bes}
+                        #guitar-tuning
+                        #(chord-shape 'bes)
+
+\storePredefinedDiagram \chordmode {c}
+                        #guitar-tuning
+                        #(offset-fret 2 (chord-shape 'bes))
+
+mychords = \chordmode {
+  bes
+}
+
+chordline = {
+  \mychords
+  \transpose bes c {
+    \mychords
+  }
+}
+
+<<
+  \context ChordNames {
+    \chordline
+  }
+  \context FretBoards {
+    \chordline
+  }
+>>
diff --git a/input/regression/tuplet-full-length-extent.ly b/input/regression/tuplet-full-length-extent.ly
new file mode 100644
index 0000000000..e2b1575c9e
--- /dev/null
+++ b/input/regression/tuplet-full-length-extent.ly
@@ -0,0 +1,20 @@
+\header {
+  
+  texidoc = "With @code{full-length-to-extent}, the extent of the
+  attaching column for a full-length tuplet bracket can be ignored."
+
+}
+\version "2.11.55"
+
+\new Staff {
+   \set tupletFullLength = ##t
+   
+   \time 1/8
+   \times 2/3 { c'16 c'16 c'16 }
+   \times 2/3 { c'16 c'16 c'16 }
+   \override TupletBracket #'full-length-to-extent = ##f
+   \times 2/3 { c'16 c'16 c'16 }
+   \override Score.RehearsalMark #'break-visibility = ##(#t #t #t)
+   \override Score.RehearsalMark #'direction = #down
+   \mark "xxxxxxxxxxxxxxxxxxxxxxx"
+}
diff --git a/lily/dot-column.cc b/lily/dot-column.cc
index b2645ba6dd..249eb9b8cd 100644
--- a/lily/dot-column.cc
+++ b/lily/dot-column.cc
@@ -15,20 +15,20 @@
 
 using namespace std;
 
-#include "dots.hh"
-#include "dot-column.hh"
-#include "rhythmic-head.hh"
-#include "staff-symbol-referencer.hh"
-#include "directional-element-interface.hh"
-#include "side-position-interface.hh"
 #include "axis-group-interface.hh"
-#include "stem.hh"
-#include "grob.hh"
-#include "pointer-group-interface.hh"
+#include "directional-element-interface.hh"
+#include "dot-column.hh"
 #include "dot-configuration.hh"
+#include "dot-formatting-problem.hh"
+#include "dots.hh"
+#include "grob.hh"
 #include "note-head.hh"
+#include "pointer-group-interface.hh"
 #include "rest.hh"
-#include "dot-formatting-problem.hh"
+#include "rhythmic-head.hh"
+#include "side-position-interface.hh"
+#include "staff-symbol-referencer.hh"
+#include "stem.hh"
 
 MAKE_SCHEME_CALLBACK (Dot_column, calc_positioning_done, 1);
 SCM
@@ -178,7 +178,6 @@ Dot_column::calc_positioning_done (SCM smob)
        */
       Staff_symbol_referencer::set_position (i->second.dot_, i->first);
     }
-
   
   me->translate_axis (cfg.x_offset () - me->relative_coordinate (commonx, X_AXIS),
 		      X_AXIS);
@@ -186,16 +185,19 @@ Dot_column::calc_positioning_done (SCM smob)
 }
 
 void
-Dot_column::add_head (Grob *me, Grob *rh)
+Dot_column::add_head (Grob *me, Grob *head)
 {
-  Grob *d = unsmob_grob (rh->get_object ("dot"));
+  Grob *d = unsmob_grob (head->get_object ("dot"));
   if (d)
     {
-      Side_position_interface::add_support (me, rh);
+      Side_position_interface::add_support (me, head);
 
       Pointer_group_interface::add_grob (me, ly_symbol2scm ("dots"), d);
       d->set_property ("Y-offset", Grob::x_parent_positioning_proc);
-      d->set_property ("X-offset", Grob::x_parent_positioning_proc);
+      // Dot formatting requests the Y-offset, -which- for rests may
+      // trigger post-linebreak callbacks.
+      if (!Rest::has_interface (head))
+	d->set_property ("X-offset", Grob::x_parent_positioning_proc);
       Axis_group_interface::add_element (me, d);
     }
 }
diff --git a/lily/dots-engraver.cc b/lily/dots-engraver.cc
index bf0d67fd0b..83eef1c05d 100644
--- a/lily/dots-engraver.cc
+++ b/lily/dots-engraver.cc
@@ -36,7 +36,6 @@ Dots_engraver::acknowledge_rhythmic_head (Grob_info gi)
   Grob *note = gi.grob ();
   if (unsmob_grob (note->get_object ("dot")))
     return;
-
   
   Duration *dur = unsmob_duration (cause->get_property ("duration"));
   if (dur && dur->dot_count ())
diff --git a/lily/fretboard-engraver.cc b/lily/fretboard-engraver.cc
index b75156f545..f284161a80 100644
--- a/lily/fretboard-engraver.cc
+++ b/lily/fretboard-engraver.cc
@@ -97,7 +97,8 @@ ADD_TRANSLATOR (Fretboard_engraver,
 		"minimumFret "
                 "maximumFretStretch "
 		"tablatureFormat "
-		"highStringOne ",
+		"highStringOne "
+                "predefinedDiagramTable",
 
 		/* write */
 		""
diff --git a/lily/main.cc b/lily/main.cc
index e0f5dda1a2..759091ee11 100644
--- a/lily/main.cc
+++ b/lily/main.cc
@@ -240,9 +240,10 @@ static void
 notice ()
 {
   identify (stdout);
-  puts (_f (NOTICE, PROGRAM_NAME).c_str ());
   printf ("\n");
   copyright ();
+  printf ("\n");
+  puts (_f (NOTICE, PROGRAM_NAME).c_str ());
 }
 
 LY_DEFINE (ly_usage, "ly:usage",
@@ -557,7 +558,6 @@ parse_argv (int argc, char **argv)
 
   if (show_help)
     {
-      identify (stdout);
       ly_usage ();
       if (be_verbose_global)
 	dir_info (stdout);
diff --git a/lily/staff-symbol-referencer.cc b/lily/staff-symbol-referencer.cc
index d623bd35b3..dbff0245c6 100644
--- a/lily/staff-symbol-referencer.cc
+++ b/lily/staff-symbol-referencer.cc
@@ -108,8 +108,6 @@ Staff_symbol_referencer::extent_in_staff (Grob *me)
   return retval;
 }
 
-
-
 int
 Staff_symbol_referencer::get_rounded_position (Grob *me)
 {
diff --git a/lily/staff-symbol.cc b/lily/staff-symbol.cc
index 6e376434ca..6fefc48010 100644
--- a/lily/staff-symbol.cc
+++ b/lily/staff-symbol.cc
@@ -170,8 +170,7 @@ Staff_symbol::height  (SCM smob)
 bool
 Staff_symbol::on_line (Grob *me, int pos)
 {
-  Grob *st = Staff_symbol_referencer::get_staff_symbol (me);
-  SCM line_positions = st->get_property ("line-positions");
+  SCM line_positions = me->get_property ("line-positions");
   if (scm_is_pair (line_positions))
     {
       Real min_line = HUGE_VAL;
@@ -195,7 +194,7 @@ Staff_symbol::on_line (Grob *me, int pos)
       return false;
     }
   else
-    return ((abs (pos + line_count (st)) % 2) == 1);
+    return ((abs (pos + line_count (me)) % 2) == 1);
 }
 
 ADD_INTERFACE (Staff_symbol,
diff --git a/lily/tuplet-bracket.cc b/lily/tuplet-bracket.cc
index dde38da22d..639472399c 100644
--- a/lily/tuplet-bracket.cc
+++ b/lily/tuplet-bracket.cc
@@ -231,17 +231,20 @@ Tuplet_bracket::calc_control_points (SCM smob)
 	  /*
 	    We're connecting to a column, for the last bit of a broken
 	    fullLength bracket.
-	    
-	    TODO: make padding tunable?
 	  */
-	  Real padding = 1.0;
+	  Real padding =
+	    robust_scm2double(me->get_property("full-length-padding"), 1.0);
 
 	  if (bounds[d]->break_status_dir ())
 	    padding = 0.0;
-	  
-	  x_span[d]
-	    = robust_relative_extent (bounds[d], commonx, X_AXIS) [LEFT]
-	    - padding;
+
+	  Real coord = bounds[d]->relative_coordinate(commonx, X_AXIS);
+	  if (to_boolean (me->get_property ("full-length-to-extent")))
+	    coord = robust_relative_extent(bounds[d], commonx, X_AXIS)[LEFT];
+
+	  coord = max (coord, x_span[LEFT]);
+
+	  x_span[d] = coord - padding;
 	}
     }
   while (flip (&d) != LEFT);
@@ -782,6 +785,8 @@ ADD_INTERFACE (Tuplet_bracket,
 	       "direction "
 	       "edge-height "
 	       "edge-text "
+	       "full-length-padding "
+	       "full-length-to-extent "
 	       "gap "
 	       "positions "
 	       "note-columns "
diff --git a/ly/declarations-init.ly b/ly/declarations-init.ly
index b8c36e4f33..88fdfe1c03 100644
--- a/ly/declarations-init.ly
+++ b/ly/declarations-init.ly
@@ -63,6 +63,7 @@ escapedBiggerSymbol = #(make-span-event 'DecrescendoEvent START)
 escapedSmallerSymbol = #(make-span-event 'CrescendoEvent START)
 
 
+#(define fretboard-table (make-hash-table 100))
 
 \include "scale-definitions-init.ly"
 
@@ -117,3 +118,6 @@ setDefaultDurationToQuarter = { c4 }
 #(define book-music-handler collect-book-music-for-book)
 #(define book-score-handler ly:book-add-score!)
 #(define book-text-handler ly:book-add-score!)
+
+
+\include "predefined-fretboards-init.ly"
diff --git a/ly/engraver-init.ly b/ly/engraver-init.ly
index ffee024a1c..022fb8a1d9 100644
--- a/ly/engraver-init.ly
+++ b/ly/engraver-init.ly
@@ -22,6 +22,8 @@
   \consists "Separating_line_group_engraver"
   \consists "Font_size_engraver"
   \consists "Instrument_name_engraver"
+
+  predefinedDiagramTable = #fretboard-table
 }
 
 \context {
diff --git a/ly/predefined-fretboards-init.ly b/ly/predefined-fretboards-init.ly
new file mode 100644
index 0000000000..c8b7ff0731
--- /dev/null
+++ b/ly/predefined-fretboards-init.ly
@@ -0,0 +1,46 @@
+%%%% predefined-fretboard-init.ly
+%%%%
+%%%% source file of the GNU LilyPond music typesetter
+%%%%
+%%%% (c) 2008 Carl D. Sorensen <c_sorensen@byu.edu>
+
+%%%%% define storage structures
+
+% base-chord-shapes is an alist of chord shapes
+% in the form of fret-diagram-terse strings with
+% scheme symbols as keys.  For convenience, the
+% symbols are LilyPond chordmode chord descriptions,
+% but that is unnecessary.
+
+#(define base-chord-shapes '())
+
+
+% music function for adding a chord shape to
+% base-chord-shapes
+
+addChordShape =
+#(define-music-function (parser location key-symbol shape-string)
+   (symbol? string?)
+   (set! base-chord-shapes 
+           (acons key-symbol shape-string base-chord-shapes))
+   (make-music 'SequentialMusic 'void #t))
+
+% for convenience, to eliminate storage list in .ly references
+
+#(define (chord-shape shape-code)
+   (get-chord-shape shape-code base-chord-shapes))
+
+% music function for adding a predefined diagram to
+% fretboard-table
+
+storePredefinedDiagram =
+#(define-music-function (parser location chord tuning terse-definition)
+  (ly:music? list? string?)
+  (let* ((pitches (event-chord-pitches 
+                    (car (extract-named-music chord 'EventChord))))
+         (hash-key (cons tuning pitches)))
+  (hash-set! fretboard-table 
+             hash-key 
+             (parse-terse-string terse-definition)))
+  (make-music 'SequentialMusic 'void #t))
+
diff --git a/ly/predefined-guitar-fretboards.ly b/ly/predefined-guitar-fretboards.ly
new file mode 100644
index 0000000000..2a08c4f002
--- /dev/null
+++ b/ly/predefined-guitar-fretboards.ly
@@ -0,0 +1,435 @@
+%%%% predefined-guitar-fretboards.ly
+%%%%
+%%%% source file of the GNU LilyPond music typesetter
+%%%%
+%%%% (c) 2008 Carl D. Sorensen <c_sorensen@byu.edu>
+
+%%%  Add basic chordshapes
+
+\addChordShape #'f #"1-1-(;3-3;3-4;2-2;1-1;1-1-);"
+\addChordShape #'f:m #"1-1-(;3-3;3-4;1-1;1-1;1-1-);"
+\addChordShape #'f:7 #"1-1-(;3-3;1-1;2-2;1-1;1-1-);"
+\addChordShape #'f:m7 #"1-1-(;3-3;1-1;1-1;1-1;1-1-);"
+\addChordShape #'bes #"x;1-1-(;3-2;3-3;3-4;1-1-);"
+\addChordShape #'bes:m #"x;1-1-(;3-3;3-4;2-2;1-1-);"
+\addChordShape #'bes:m7 #"x;1-1-(;3-3;1-1;2-2;1-1-);"
+\addChordShape #'bes:7 #"x;1-1-(;3-2;1-1;3-3;1-1-);"
+\addChordShape #'bes:maj7 #"x;1-1;3-3;2-2;3-4;x;"
+\addChordShape #'c:dim #"x;x;1-1;2-3;1-2;2-4;"
+\addChordShape #'c:aug #"x;x;2-2;1-1-(;1-1-);4-4;"
+\addChordShape #'cis #"x;x;3-3;1-1-(;2-2;1-1-);"
+\addChordShape #'ees:dim #"x;x;1-1;2-3;1-2;2-4;"
+\addChordShape #'a:dim #"x;x;1-1;2-3;1-2;2-4;"
+
+%%%  Add predefined chords
+
+% definitions of predefined diagrams below here
+
+%%%%  c chords
+%
+\storePredefinedDiagram \chordmode {c}
+                        #guitar-tuning 
+                        #"x;3-3;2-2;o;1-1;o;"  
+\storePredefinedDiagram \chordmode {c:m} 
+                        #guitar-tuning 
+                        #(offset-fret 2 (chord-shape 'bes:m))
+\storePredefinedDiagram \chordmode {c:aug} 
+                        #guitar-tuning 
+                        #(chord-shape 'c:aug)
+\storePredefinedDiagram \chordmode {c:dim} 
+                        #guitar-tuning 
+                        #(chord-shape 'c:dim)
+\storePredefinedDiagram \chordmode {c:7} 
+                        #guitar-tuning 
+                        #"o;3-3;2-2;3-4;1-1;o;"  
+\storePredefinedDiagram \chordmode {c:maj7} 
+                        #guitar-tuning 
+                        #"x;3-3;2-2;o;o;o;"  
+\storePredefinedDiagram \chordmode {c:m7} 
+                        #guitar-tuning 
+                        #(offset-fret 2 (chord-shape 'bes:m7))
+
+%%%%  cis chords
+%
+\storePredefinedDiagram \chordmode {cis} 
+                        #guitar-tuning 
+                        #(chord-shape 'cis)
+\storePredefinedDiagram \chordmode {cis:m} 
+                        #guitar-tuning 
+                        #"x;x;2-2;1-1;2-3;o;"  
+\storePredefinedDiagram \chordmode {cis:aug} 
+                        #guitar-tuning 
+                        #"x;4-4;3-3;2-1;2-2;x;"  
+\storePredefinedDiagram \chordmode {cis:dim} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'c:dim))
+\storePredefinedDiagram \chordmode {cis:7} 
+                        #guitar-tuning 
+                        #"x;x;3-2;4-3;2-1;4-4;"  
+\storePredefinedDiagram \chordmode {cis:maj7} 
+                        #guitar-tuning 
+                        #"x;4-4;3-3;1-1-(;1-1;1-1-);"  
+\storePredefinedDiagram \chordmode {cis:m7} 
+                        #guitar-tuning 
+                        #"x;4-4;2-2;1-1;o;o;"
+
+%%%%  des chords
+%
+\storePredefinedDiagram \chordmode {des} 
+                        #guitar-tuning 
+                        #"x;x;3-3;1-1-(;2-2;1-1-);"  
+\storePredefinedDiagram \chordmode {des:m} 
+                        #guitar-tuning 
+                        #"x;x;2-2;1-1;2-3;o;"  
+\storePredefinedDiagram \chordmode {des:aug} 
+                        #guitar-tuning 
+                        #"x;4-4;3-3;2-1;2-2;x;"  
+\storePredefinedDiagram \chordmode {des:dim} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'c:dim))
+\storePredefinedDiagram \chordmode {des:7} 
+                        #guitar-tuning 
+                        #"x;x;3-2;4-3;2-1;4-4;"  
+\storePredefinedDiagram \chordmode {des:maj7} 
+                        #guitar-tuning 
+                        #"x;4-4;3-3;1-1-(;1-1;1-1-);"  
+\storePredefinedDiagram \chordmode {des:m7} 
+                        #guitar-tuning 
+                        #"x;4-4;2-2;1-1;o;o;"
+
+%%%%  d chords
+%
+\storePredefinedDiagram \chordmode {d} 
+                        #guitar-tuning 
+                        #"x;x;o;2-1;3-2;2-3;"  
+\storePredefinedDiagram \chordmode {d:m} 
+                        #guitar-tuning 
+                        #"x;x;o;2-2;3-3;1-1;"  
+\storePredefinedDiagram \chordmode {d:aug} 
+                        #guitar-tuning 
+                        #"x;x;o;3-2;3-3;2-1;"  
+\storePredefinedDiagram \chordmode {d:dim} 
+                        #guitar-tuning 
+                        #"x;x;o;1-1;o;1-2;"  
+\storePredefinedDiagram \chordmode {d:7} 
+                        #guitar-tuning 
+                        #"x;x;o;2-2;1-1;2-3;"  
+\storePredefinedDiagram \chordmode {d:maj7} 
+                        #guitar-tuning 
+                        #"x;x;o;2-1;2-2;2-3;"  
+\storePredefinedDiagram \chordmode {d:m7} 
+                        #guitar-tuning 
+                        #"x;x;o;2-2;1-1-(;1-1-);"  
+
+%%%%  dis chords
+%
+\storePredefinedDiagram \chordmode {dis} 
+                        #guitar-tuning 
+                        #(offset-fret 2 (chord-shape 'cis))
+\storePredefinedDiagram \chordmode {dis:m} 
+                        #guitar-tuning 
+                        #"x;x;4-3;3-2;4-4;1-1;"  
+\storePredefinedDiagram \chordmode {dis:aug} 
+                        #guitar-tuning 
+                        #"3-3;2-2;1-1;o;o;3-4"  
+\storePredefinedDiagram \chordmode {dis:dim} 
+                        #guitar-tuning 
+                        #(chord-shape 'ees:dim) 
+\storePredefinedDiagram \chordmode {dis:7} 
+                        #guitar-tuning 
+                        #"x;x;1-1;3-3;2-2;3-4;"  
+\storePredefinedDiagram \chordmode {dis:maj7} 
+                        #guitar-tuning 
+                        #"x;x;1-1;3-2;3-3;3-4;"  
+\storePredefinedDiagram \chordmode {dis:m7} 
+                        #guitar-tuning 
+                        #"x;x;1-1;3-2;2-3;2-4;"  
+
+%%%%  ees chords
+%
+\storePredefinedDiagram \chordmode {ees} 
+                        #guitar-tuning 
+                        #(offset-fret 2 (chord-shape 'cis))
+\storePredefinedDiagram \chordmode {ees:m} 
+                        #guitar-tuning 
+                        #"x;x;4-3;3-2;4-4;1-1;"  
+\storePredefinedDiagram \chordmode {ees:aug} 
+                        #guitar-tuning 
+                        #"3-3;2-2;1-1;o;o;3-4"  
+\storePredefinedDiagram \chordmode {ees:dim} 
+                        #guitar-tuning 
+                        #(chord-shape 'ees:dim) 
+\storePredefinedDiagram \chordmode {ees:7} 
+                        #guitar-tuning 
+                        #"x;x;1-1;3-3;2-2;3-4;"  
+\storePredefinedDiagram \chordmode {ees:maj7} 
+                        #guitar-tuning 
+                        #"x;x;1-1;3-2;3-3;3-4;"  
+\storePredefinedDiagram \chordmode {ees:m7} 
+                        #guitar-tuning 
+                        #"x;x;1-1;3-2;2-3;2-4;"  
+
+%%%%  e chords
+%
+\storePredefinedDiagram \chordmode {e} 
+                        #guitar-tuning 
+                        #"o;2-2;2-3;1-1;o;o;"  
+\storePredefinedDiagram \chordmode {e:m} 
+                        #guitar-tuning 
+                        #"o;2-2;2-3;o;o;o;"  
+\storePredefinedDiagram \chordmode {e:aug} 
+                        #guitar-tuning 
+                        #"o;3-3;2-2;1-1;x;x;"  
+\storePredefinedDiagram \chordmode {e:dim} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'ees:dim))
+\storePredefinedDiagram \chordmode {e:7} 
+                        #guitar-tuning 
+                        #"o;2-2;o;1-1;o;o;"  
+\storePredefinedDiagram \chordmode {e:maj7} 
+                        #guitar-tuning 
+                        #"o;2-3;1-1;1-2;o;x;"  
+\storePredefinedDiagram \chordmode {e:m7} 
+                        #guitar-tuning 
+                        #"o;2-2;o;o;o;o;"  
+
+%%%%  f chords
+%
+\storePredefinedDiagram \chordmode {f} 
+                        #guitar-tuning 
+                        #(chord-shape 'f)
+\storePredefinedDiagram \chordmode {f:m} 
+                        #guitar-tuning 
+                        #(chord-shape 'f:m)
+\storePredefinedDiagram \chordmode {f:aug} 
+                        #guitar-tuning 
+                        #"x;x;1-1;4-3;4-4;3-2;"  
+\storePredefinedDiagram \chordmode {f:dim} 
+                        #guitar-tuning 
+                        #"x;x;o;1-1;o;1-2;"  
+\storePredefinedDiagram \chordmode {f:7} 
+                        #guitar-tuning 
+                        #(chord-shape 'f:7)
+\storePredefinedDiagram \chordmode {f:maj7} 
+                        #guitar-tuning 
+                        #"x;3-3;3-4;2-2;1-1;"  
+\storePredefinedDiagram \chordmode {f:m7} 
+                        #guitar-tuning 
+                        #(chord-shape 'f:m7)
+
+%%%%  fis chords
+%
+\storePredefinedDiagram \chordmode {fis} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'f))
+\storePredefinedDiagram \chordmode {fis:m} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'f:m))
+\storePredefinedDiagram \chordmode {fis:aug} 
+                        #guitar-tuning 
+                        #"2-2;1-1;o;3-4-(;3-4-);2-3;" 
+\storePredefinedDiagram \chordmode {fis:dim} 
+                        #guitar-tuning 
+                        #"x;x;1-1;2-3;1-2;2-4;"  
+\storePredefinedDiagram \chordmode {fis:7} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'f:7))
+\storePredefinedDiagram \chordmode {fis:maj7} 
+                        #guitar-tuning 
+                        #"x;x;4-4;3-3;2-2;1-1;"  
+\storePredefinedDiagram \chordmode {fis:m7} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'f:m7))
+
+%%%%  ges chords
+%
+\storePredefinedDiagram \chordmode {ges} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'f))
+\storePredefinedDiagram \chordmode {ges:m} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'f:m))
+\storePredefinedDiagram \chordmode {ges:aug} 
+                        #guitar-tuning 
+                        #"2-2;1-1;o;3-4-(;3-4-);2-3;" 
+\storePredefinedDiagram \chordmode {ges:dim} 
+                        #guitar-tuning 
+                        #"x;x;1-1;2-3;1-2;2-4;"  
+\storePredefinedDiagram \chordmode {ges:7} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'f:7))
+\storePredefinedDiagram \chordmode {ges:maj7} 
+                        #guitar-tuning 
+                        #"x;x;4-4;3-3;2-2;1-1;"  
+\storePredefinedDiagram \chordmode {ges:m7} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'f:m7))
+
+%%%%  g chords
+%
+\storePredefinedDiagram \chordmode {g} 
+                        #guitar-tuning 
+                        #"3-2;2-1;o;o;o;3-3;"  
+\storePredefinedDiagram \chordmode {g:m} 
+                        #guitar-tuning 
+                        #(offset-fret 2 (chord-shape 'f:m))
+\storePredefinedDiagram \chordmode {g:aug} 
+                        #guitar-tuning 
+                        #"x;x;5-1;8-3;8-4;7-2;"  
+\storePredefinedDiagram \chordmode {g:dim} 
+                        #guitar-tuning 
+                        #"x;x;5-2;6-4;5-3;3-1;"  
+\storePredefinedDiagram \chordmode {g:7} 
+                        #guitar-tuning 
+                        #"3-3;2-2;o;o;o;1-1;"  
+\storePredefinedDiagram \chordmode {g:maj7} 
+                        #guitar-tuning 
+                        #"x;x;5-4;4-3;3-2;2-1;"  
+\storePredefinedDiagram \chordmode {g:m7} 
+                        #guitar-tuning 
+                        #(offset-fret 2 (chord-shape 'f:m7))
+
+%%%%  gis chords
+%
+\storePredefinedDiagram \chordmode {gis} 
+                        #guitar-tuning 
+                        #(offset-fret 3 (chord-shape 'f))
+\storePredefinedDiagram \chordmode {gis:m} 
+                        #guitar-tuning 
+                        #(offset-fret 3 (chord-shape 'f:m))
+\storePredefinedDiagram \chordmode {gis:aug} 
+                        #guitar-tuning 
+                        #"o;3-4;2-3;1-1;1-2;o;"  
+\storePredefinedDiagram \chordmode {gis:dim} 
+                        #guitar-tuning 
+                        #"x;x;o;1-1;o;1-2;"  
+\storePredefinedDiagram \chordmode {gis:7} 
+                        #guitar-tuning 
+                        #(offset-fret 3 (chord-shape 'f:7))
+\storePredefinedDiagram \chordmode {gis:maj7} 
+                        #guitar-tuning 
+                        #"x;x;1-1-(;1-1;1-1-);3-3;"  
+\storePredefinedDiagram \chordmode {gis:m7} 
+                        #guitar-tuning 
+                        #(offset-fret 3 (chord-shape 'f:m7))
+
+%%%%  aes chords
+%
+\storePredefinedDiagram \chordmode {aes} 
+                        #guitar-tuning 
+                        #(offset-fret 3 (chord-shape 'f))
+\storePredefinedDiagram \chordmode {aes:m} 
+                        #guitar-tuning 
+                        #(offset-fret 3 (chord-shape 'f:m))
+\storePredefinedDiagram \chordmode {aes:aug} 
+                        #guitar-tuning 
+                        #"o;3-4;2-3;1-1;1-2;o;"  
+\storePredefinedDiagram \chordmode {aes:dim} 
+                        #guitar-tuning 
+                        #"x;x;o;1-1;o;1-2;"  
+\storePredefinedDiagram \chordmode {aes:7} 
+                        #guitar-tuning 
+                        #(offset-fret 3 (chord-shape 'f:7))
+\storePredefinedDiagram \chordmode {aes:maj7} 
+                        #guitar-tuning 
+                        #"x;x;1-1-(;1-1;1-1-);3-3;"  
+\storePredefinedDiagram \chordmode {aes:m7} 
+                        #guitar-tuning 
+                        #(offset-fret 3 (chord-shape 'f:m7))
+
+%%%%  a chords
+%
+\storePredefinedDiagram \chordmode {a} 
+                        #guitar-tuning 
+                        #"x;o;2-1;2-2;2-3;o;"  
+\storePredefinedDiagram \chordmode {a:m} 
+                        #guitar-tuning 
+                        #"x;o;2-2;2-3;1-1;o;"  
+\storePredefinedDiagram \chordmode {a:aug} 
+                        #guitar-tuning 
+                        #"x;o;3-4;2-2;2-3;1-1;"  
+\storePredefinedDiagram \chordmode {a:dim} 
+                        #guitar-tuning 
+                        #(chord-shape 'a:dim)
+\storePredefinedDiagram \chordmode {a:7} 
+                        #guitar-tuning 
+                        #"x;o;2-1;o;2-3;o;"  
+\storePredefinedDiagram \chordmode {a:maj7} 
+                        #guitar-tuning 
+                        #"x;o;2-2;1-1;2-3;o;"  
+\storePredefinedDiagram \chordmode {a:m7} 
+                        #guitar-tuning 
+                        #"x;o;2-2;o;1-1;o;"  
+
+%%%%  ais chords
+%
+\storePredefinedDiagram \chordmode {ais} 
+                        #guitar-tuning 
+                        #(chord-shape 'bes)
+\storePredefinedDiagram \chordmode {ais:m} 
+                        #guitar-tuning 
+                        #(chord-shape 'bes:m)
+\storePredefinedDiagram \chordmode {ais:aug} 
+                        #guitar-tuning 
+                        #"2-2;1-1;o;3-4-(;3-4-);2-3;"  
+\storePredefinedDiagram \chordmode {ais:dim} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'a:dim))
+\storePredefinedDiagram \chordmode {ais:7} 
+                        #guitar-tuning 
+                        #(chord-shape 'bes:7)
+\storePredefinedDiagram \chordmode {ais:maj7} 
+                        #guitar-tuning 
+                        #"x;1-1;3-3;2-2;3-4;x;"  
+\storePredefinedDiagram \chordmode {ais:m7} 
+                        #guitar-tuning 
+                        #(chord-shape 'bes:m7)
+
+%%%%  bes chords
+%
+\storePredefinedDiagram \chordmode {bes} 
+                        #guitar-tuning 
+                        #(chord-shape 'bes)
+\storePredefinedDiagram \chordmode {bes:m} 
+                        #guitar-tuning 
+                        #(chord-shape 'bes:m)
+\storePredefinedDiagram \chordmode {bes:aug} 
+                        #guitar-tuning 
+                        #"2-2;1-1;o;3-4-(;3-4-);2-3;"  
+\storePredefinedDiagram \chordmode {bes:dim} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'a:dim))
+\storePredefinedDiagram \chordmode {bes:7} 
+                        #guitar-tuning 
+                        #(chord-shape 'bes:7)
+\storePredefinedDiagram \chordmode {bes:maj7} 
+                        #guitar-tuning 
+                        #"x;1-1;3-3;2-2;3-4;x;"  
+\storePredefinedDiagram \chordmode {bes:m7} 
+                        #guitar-tuning 
+                        #(chord-shape 'bes:m7)
+
+%%%%  b chords
+%
+\storePredefinedDiagram \chordmode {b} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'bes))
+\storePredefinedDiagram \chordmode {b:m} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'bes:m))
+\storePredefinedDiagram \chordmode {b:aug} 
+                        #guitar-tuning 
+                        #"x;3-2;2-1;o;o;x;"  
+\storePredefinedDiagram \chordmode {b:dim} 
+                        #guitar-tuning 
+                        #"x;x;o;1-1;o;1-2;"  
+\storePredefinedDiagram \chordmode {b:7} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'bes:7))
+\storePredefinedDiagram \chordmode {b:maj7} 
+                        #guitar-tuning 
+                        #"x;2-1;4-3;3-2;4-4;x;"  
+\storePredefinedDiagram \chordmode {b:m7} 
+                        #guitar-tuning 
+                        #(offset-fret 1 (chord-shape 'bes:m7))
+
diff --git a/ly/property-init.ly b/ly/property-init.ly
index 9098d313cf..0ed5d49f5b 100644
--- a/ly/property-init.ly
+++ b/ly/property-init.ly
@@ -341,3 +341,11 @@ bassFigureStaffAlignmentNeutral = {
   \revert Staff.BassFigureAlignmentPositioning #'direction
 }
 
+predefinedFretboardsOff = {  
+  \set FretBoards.predefinedDiagramTable = ##f
+}
+
+predefinedFretboardsOn = {
+  \set FretBoards.predefinedDiagramTable = #fretboard-table
+}
+
diff --git a/scm/define-context-properties.scm b/scm/define-context-properties.scm
index a9ca43f9f7..cbd0e1544b 100644
--- a/scm/define-context-properties.scm
+++ b/scm/define-context-properties.scm
@@ -345,6 +345,8 @@ the pedal.")
 sustain pedals: @code{text}, @code{bracket} or @code{mixed} (both).")
      (pedalUnaCordaStrings ,list? "See @code{pedalSustainStrings}.")
      (pedalUnaCordaStyle ,symbol? "See @code{pedalSustainStyle}.")
+     (predefinedDiagramTable ,hash-table? "The hash table of predefined
+fret diagrams to use in FretBoards.")
      (printKeyCancellation ,boolean? "Print restoration alterations
 before a key signature change.")
      (printOctaveNames ,boolean? "Print octave marks for the
@@ -466,8 +468,7 @@ setting this property, you can make brackets last shorter.
 
      (useBassFigureExtenders ,boolean? "Whether to use extender lines
 for repeated bass figures.")
-
-
+     
      (verticallySpacedContexts ,list? "List of symbols, containing
 context names whose vertical axis groups should be taken into account
 for vertical spacing of systems.")
diff --git a/scm/define-grob-interfaces.scm b/scm/define-grob-interfaces.scm
index d5f5d36fcd..8b0dde24f8 100644
--- a/scm/define-grob-interfaces.scm
+++ b/scm/define-grob-interfaces.scm
@@ -53,7 +53,7 @@ note)."
 (ly:add-interface
  'fret-diagram-interface
  "A fret diagram"
- '(align-dir fret-diagram-details size string-fret-finger-combinations
+ '(align-dir fret-diagram-details size dot-placement-list
    thickness))
 
 (ly:add-interface
diff --git a/scm/define-grob-properties.scm b/scm/define-grob-properties.scm
index 7e57b5e8a7..8d2de51b14 100644
--- a/scm/define-grob-properties.scm
+++ b/scm/define-grob-properties.scm
@@ -168,6 +168,10 @@ other object.  Otherwise, it determines whether the object is placed
 be used: @code{#UP}=@code{1}, @code{#DOWN}=@code{-1},
 @code{#LEFT}=@code{-1}, @code{#RIGHT}=@code{1}, @code{#CENTER}=@code{0}.")
      (dot-count ,integer? "The number of dots.")
+     (dot-placement-list ,list? "List 
+consisting of @code{@var{description} (@var{string-number} 
+@var{fret-number} @var{finger-number})} 
+entries used to define fret diagrams.")
      (duration-log ,integer? "The 2-log of the note head duration,
 i.e., @code{0} = whole note, @code{1} = half note, etc.")
 
@@ -290,10 +294,13 @@ open string indicators.  Default value 0.5.
 @item
 @code{xo-padding} -- Padding for open and mute indicators from top fret.  Default
 value 0.25.
-@end itemize")
+@end itemize")      ;"
 
 
     ;; ugh: double, change.
+     (full-length-padding ,number? "How much padding to use at the right side of a full-length tuplet bracket.")
+     (full-length-to-extent ,boolean? "Run to the extent of the column for a full-length tuplet bracket.")
+     
      (full-size-change ,boolean? "Don't make a change clef smaller.")
 
      (gap ,ly:dimension? "Size of a gap in a variable symbol.")
@@ -563,9 +570,6 @@ are not spaced separately, but put before musical columns.")
      (strict-note-spacing ,boolean? "If set, unbroken columns
 with non-musical material (clefs, bar lines, etc.) are not spaced
 separately, but put before musical columns.")
-     (string-fret-finger-combinations ,list? "List consisting of
-@code{(@var{string-number} @var{fret-number} @var{finger-number})}
-entries.")
      (stroke-style ,string? "Set to @code{\"grace\"} to turn stroke
 through flag on.")
      (style ,symbol? "This setting determines in what style a grob is
diff --git a/scm/define-grobs.scm b/scm/define-grobs.scm
index ab6b270f24..84c0e5fae6 100644
--- a/scm/define-grobs.scm
+++ b/scm/define-grobs.scm
@@ -2044,6 +2044,7 @@
 	(edge-height . (0.7 . 0.7))
 	(shorten-pair . (-0.2 . -0.2))
 	(staff-padding . 0.25)
+	(full-length-to-extent . #t)
 	(direction  . ,ly:tuplet-bracket::calc-direction)
 	(positions . ,ly:tuplet-bracket::calc-positions)
 	(connect-to-neighbor . ,ly:tuplet-bracket::calc-connect-to-neighbors)
@@ -2249,6 +2250,7 @@
 
 (define pure-print-callbacks
   (list
+   fret-board::calc-stencil
    print-circled-text-callback
    lyric-text::print
    ly:arpeggio::print
diff --git a/scm/framework-ps.scm b/scm/framework-ps.scm
index 44427dbd09..c7214da3c5 100644
--- a/scm/framework-ps.scm
+++ b/scm/framework-ps.scm
@@ -535,19 +535,22 @@
 (define-public (dump-stencil-as-EPS-with-bbox paper dump-me filename
 					      load-fonts
 					      bbox)
-  (define (to-bp-box mmbox)
+  "Create an EPS file from stencil DUMP-ME to FILENAME. BBOX has format
+   (left-x, lower-y, right x, up-y).  If LOAD-FONTS set, include fonts inline." 
+
+  (define (to-rounded-bp-box box)
+    "Convert box to 1/72 inch with rounding to enlarge the box."
     (let* ((scale (ly:output-def-lookup paper 'output-scale))
-	   (box (map
-		 (lambda (x)
-		   (if (or (nan? x) (inf? x))
-		       0
-		       (inexact->exact
-			(round (/ (* x scale) (ly:bp 1)))))) mmbox)))
-      
-    (list (car box)
-	  (cadr box)
-	  (max (1+ (car box)) (caddr box))
-	  (max (1+ (cadr box)) (cadddr box))
+	   (strip-non-number (lambda (x)
+			       (if (or (nan? x) (inf? x)) 0.0 x)))
+	   (directed-round (lambda (x rounder)
+			     (inexact->exact
+			      (rounder (/ (* (strip-non-number x) scale)
+					  (ly:bp 1)))))))
+      (list (directed-round (car box) floor)
+	    (directed-round (cadr box) floor)
+	    (directed-round (max (1+ (car box)) (caddr box)) ceiling)
+	    (directed-round (max (1+ (cadr box)) (cadddr box)) ceiling)
 	  )))
 
   (let* ((outputter (ly:make-paper-outputter
@@ -558,7 +561,7 @@
 		     'ps))
 
 	 (port (ly:outputter-port outputter))
-	 (rounded-bbox (to-bp-box bbox))
+	 (rounded-bbox (to-rounded-bp-box bbox))
 	 (port (ly:outputter-port outputter))
 	 (header (eps-header paper rounded-bbox load-fonts)))
 
@@ -597,7 +600,7 @@
 	   ((xext (car ext-system-pair))
 	    (paper-system (cdr ext-system-pair))
 	    (yext (paper-system-extent paper-system Y))
-	    (bbox (list (car  xext) (car yext)
+	    (bbox (list (car xext) (car yext)
 			(cdr xext) (cdr yext)))
 	    (filename (if (< 0 count)
 			  (format "~a-~a" basename count)
diff --git a/scm/fret-diagrams.scm b/scm/fret-diagrams.scm
index 6378f7d12f..84d9453828 100644
--- a/scm/fret-diagrams.scm
+++ b/scm/fret-diagrams.scm
@@ -2,7 +2,7 @@
 ;;;;
 ;;;;  source file of the GNU LilyPond music typesetter
 ;;;;
-;;;; (c) 2004--2007 Carl D. Sorensen <c_sorensen@byu.edu>
+;;;; (c) 2004--2008 Carl D. Sorensen <c_sorensen@byu.edu>
 
 (define (fret-parse-marking-list marking-list fret-count)
   (let* ((fret-range (list 1 fret-count))
@@ -366,7 +366,8 @@ Line thickness is given by @var{th}, fret & string spacing by
 		  (make-bezier-sandwich-list
 		   (* size barre-start-string-coordinate)
 		   (* size barre-end-string-coordinate)
-                   (* size (+ 2 (- top-fret (+ low-fret barre-fret-coordinate))))
+                   (* size (+ 2 (- top-fret 
+                                   (+ low-fret barre-fret-coordinate))))
 		   (* size bezier-height)
 		   (* size bezier-thick)
 		   orientation)
@@ -823,7 +824,8 @@ with @code{-(} to start a barre and @code{-)} to end the barre.
 				 (car definition-list)
 				 (cdr definition-list))))
 
-(define (fret-parse-terse-definition-string props definition-string)
+(define-public 
+  (fret-parse-terse-definition-string props definition-string)
   "Parse a fret diagram string that uses terse syntax; return a pair containing:
     props, modified to include the string-count determined by the
     definition-string, and
diff --git a/scm/lily.scm b/scm/lily.scm
index b8f9a672b7..51038bcd29 100644
--- a/scm/lily.scm
+++ b/scm/lily.scm
@@ -338,7 +338,8 @@ The syntax is the same as `define*-public'."
 	    "encoding.scm"
 	    
 	    "fret-diagrams.scm"
-	    "define-markup-commands.scm"
+	    "predefined-fretboards.scm"
+            "define-markup-commands.scm"
 	    "define-grob-properties.scm"
 	    "define-grobs.scm"
 	    "define-grob-interfaces.scm"
@@ -546,6 +547,8 @@ The syntax is the same as `define*-public'."
 
 
 (define (multi-fork count)
+  "Split this process in COUNT helpers. Returns either a list of pids,
+or the number of the process."
   (define (helper count acc)
     (if (> count 0)
       (let*
@@ -593,7 +596,6 @@ The syntax is the same as `define*-public'."
   
   (if (and (number? (ly:get-option 'job-count))
 	   (>= (length files) (ly:get-option 'job-count)))
-      
       (let*
 	  ((count (ly:get-option 'job-count))
 	   (split-todo (split-list files count)) 
@@ -605,8 +607,9 @@ The syntax is the same as `define*-public'."
 	
 	(if (number? joblist)
 	    (begin
-	      (ly:set-option 'log-file (format "~a-~a"
-					       (ly:get-option 'log-file) joblist))
+	      (ly:set-option
+	       'log-file (format "~a-~a"
+				 (ly:get-option 'log-file) joblist))
 	      (set! files (vector-ref split-todo joblist)))
 
 	    (begin
@@ -616,25 +619,29 @@ The syntax is the same as `define*-public'."
 		 (let* ((stat (cdr (waitpid pid))))
 		   
 		   (if (not (= stat 0))
-		       (set! errors (acons (list-element-index joblist pid) stat errors)))))
+		       (set! errors
+			     (acons (list-element-index joblist pid)
+				    stat errors)))))
 	       joblist)
 
 	      (for-each
 	       (lambda (x)
 		 (let* ((job (car x))
 			(state (cdr x))
-			(logfile  (format "~a-~a.log"
+			(logfile (format "~a-~a.log"
 					  (ly:get-option 'log-file) job))
 			(log (ly:gulp-file logfile))
 			(len (string-length log))
 			(tail (substring  log (max 0 (- len 1024)))))
 
 		   (if (status:term-sig state)
-		       (ly:message "\n\n~a\n"
-				   (format (_ "job ~a terminated with signal: ~a")
-					   job
-					   (status:term-sig state)))
-		       (ly:message (_ "logfile ~a (exit ~a):\n~a") logfile (status:exit-val state) tail))))
+		       (ly:message
+			"\n\n~a\n"
+			(format (_ "job ~a terminated with signal: ~a")
+				job (status:term-sig state)))
+		       (ly:message
+			(_ "logfile ~a (exit ~a):\n~a")
+			logfile (status:exit-val state) tail))))
 
 	       errors)
 
@@ -646,18 +653,15 @@ The syntax is the same as `define*-public'."
 		  (dump-profile "lily-run-total" '(0 0) (profile-measurements)))
 
 	    (exit (if (null? errors) 0 1))))))
-	      
 	   
   (if (string-or-symbol? (ly:get-option 'log-file))
       (ly:stderr-redirect (format "~a.log" (ly:get-option 'log-file)) "w"))
-
   
   (let ((failed (lilypond-all files)))
     (if (ly:get-option 'trace-scheme-coverage)
 	(begin
 	  (coverage:show-all (lambda (f) (string-contains f "lilypond"))
 			     )))
-	  
     
     (if (pair? failed)
 	(begin
@@ -671,6 +675,11 @@ The syntax is the same as `define*-public'."
 (define-public (lilypond-all files)
   (let* ((failed '())
 	 (separate-logs (ly:get-option 'separate-log-files))
+	 (ping-log
+	  (if separate-logs
+	      (open-file (if (string-or-symbol? (ly:get-option 'log-file))
+			     (format "~a.log" (ly:get-option 'log-file))
+			     "/dev/tty") "a") #f))
 	 (do-measurements (ly:get-option 'dump-profile))
 	 (handler (lambda (key failed-file)
 		    (set! failed (append (list failed-file) failed)))))
@@ -687,6 +696,9 @@ The syntax is the same as `define*-public'."
 
 	 (if separate-logs
 	     (ly:stderr-redirect (format "~a.log" base) "w"))
+	 (if ping-log
+	     (format ping-log "Procesing ~a\n" base))
+	      
 	 (if (ly:get-option 'trace-memory-frequency) 
 	     (mtrace:start-trace  (ly:get-option 'trace-memory-frequency)))
 	 
@@ -718,12 +730,9 @@ The syntax is the same as `define*-public'."
      files)
 
     ;; we want the failed-files notice in the aggregrate logfile.
-    (if (ly:get-option 'separate-logs)
-	(ly:stderr-redirect
-	 (if (string-or-symbol? (ly:get-option 'log-file))
-	     (format "~a.log" (ly:get-option 'log-file))
-	     "/dev/tty") "a"))
-
+    (if ping-log
+	(format ping-log "Failed files: ~a\n" failed))
+	 
     (if (ly:get-option 'dump-profile)
 	(dump-profile "lily-run-total" '(0 0) (profile-measurements)))
 
diff --git a/scm/music-functions.scm b/scm/music-functions.scm
index c700f190db..5ca4d309af 100644
--- a/scm/music-functions.scm
+++ b/scm/music-functions.scm
@@ -1002,3 +1002,34 @@ use GrandStaff as a context. "
 	(ly:music-property (car evs) 'pitch)
 	#f)))
        
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(define-public (extract-named-music music music-name)
+"Return a flat list of all music named @code{music-name}
+from @code{music}."
+   (let ((extracted-list
+          (if (ly:music? music)
+              (if (eq? (ly:music-property music 'name) music-name)
+                  (list music)
+                  (let ((elt (ly:music-property music 'element))
+                        (elts (ly:music-property music 'elements)))
+                    (if (ly:music? elt)
+                        (extract-named-music elt music-name)
+                        (if (null? elts)
+                            '()
+                            (map (lambda(x) 
+                                    (extract-named-music x music-name ))
+                             elts)))))
+              '())))
+     (flatten-list extracted-list)))
+
+(define-public (event-chord-notes event-chord)
+"Return a list of all notes from @{event-chord}."
+  (filter
+    (lambda (m) (eq? 'NoteEvent (ly:music-property m 'name)))
+    (ly:music-property event-chord 'elements)))
+
+(define-public (event-chord-pitches event-chord)
+"Return a list of all pitches from @{event-chord}."
+  (map (lambda (x) (ly:music-property x 'pitch))
+       (event-chord-notes event-chord)))
diff --git a/scm/output-lib.scm b/scm/output-lib.scm
index de4e658fe4..7a50af6c1e 100644
--- a/scm/output-lib.scm
+++ b/scm/output-lib.scm
@@ -650,44 +650,11 @@ centered, X==1 is at the right, X == -1 is at the left."
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; fret boards
 
-(define (string-frets->description string-frets string-count)
-  (let*
-      ((desc (list->vector
-	      (map (lambda (x) (list 'mute  (1+ x)))
-		   (iota string-count)))))
-       
-       (for-each (lambda (sf)
-		   (let*
-		       ((string (car sf))
-			(fret (cadr sf))
-			(finger (caddr sf)))
-
-		     
-		     (vector-set! desc (1- string)
-				  (if (= 0 fret)
-				      (list 'open string)
-				      (if finger
-					  (list 'place-fret string fret finger) 
-					  (list 'place-fret string fret))
-					  
-
-				      ))
-		     ))
-		 string-frets)
-
-       (vector->list desc)))
-
 (define-public (fret-board::calc-stencil grob)
-  (let* ((string-frets (ly:grob-property grob 'string-fret-finger-combinations))
-	 (string-count (assoc-get 
-                         'string-count 
-                         (ly:grob-property grob 'fret-diagram-details)
-                         6)))
-    
     (grob-interpret-markup 
       grob
       (make-fret-diagram-verbose-markup
-	(string-frets->description string-frets string-count)))))
+        (ly:grob-property grob 'dot-placement-list))))
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;; scripts
diff --git a/scm/predefined-fretboards.scm b/scm/predefined-fretboards.scm
new file mode 100644
index 0000000000..7040add95e
--- /dev/null
+++ b/scm/predefined-fretboards.scm
@@ -0,0 +1,68 @@
+;;;;  predefined-fretboards.scm
+;;;;
+;;;;  source file of the GNU LilyPOnd music typesetter
+;;;;
+;;;; (c) 2008 Carl D. Sorensen <c_sorensen@byu.edu>
+
+
+(define-public (parse-terse-string terse-definition)
+"Parse a fret-diagram-terse definition string @code{terse-definition} and
+return a marking list, which can be used as with a fretboard grob."
+   (cdr (fret-parse-terse-definition-string (list '()) terse-definition)))
+
+(define-public (get-chord-shape shape-code base-chord-shapes)
+"Return the chord shape associated with key @code{shape-code} in
+the alist @code{base-chord-shapes}."
+   (assoc-get shape-code base-chord-shapes #f))
+
+(define-public (offset-fret fret-offset terse-string)
+"Add @code{fret-offset} to each fret indication in @code{terse-string}
+and return the resulting fret-diagram-terse definition string."
+
+   (define (split-fretstring fret-string)
+     (map (lambda (x) (split-item x))
+          (string-split fret-string #\sp )))
+
+   (define (split-item item-string)
+     (string-split item-string #\- ))
+
+   (define (split-terse-string terse-string)
+      (let ((long-list
+               (string-split terse-string #\;)))
+        (map (lambda (x) (split-fretstring x))
+           (list-head long-list (1- (length long-list))))))
+
+   (define (join-terse-string terse-string-list)
+     (string-join
+        (map (lambda (x) (join-fretstring x)) terse-string-list)
+        ";" 'suffix))
+
+   (define (join-item item-list)
+     (string-join item-list "-" ))
+
+   (define (join-fretstring fretstring-list)
+     (string-join
+       (map (lambda (x) (join-item x)) fretstring-list)
+       " " ))
+
+  (define (add-item-fret-offset fret-offset item-list)
+     (let ((fretval (string->number (car item-list))))
+       (if fretval
+           (cons (number->string (+ fretval fret-offset))
+                 (cdr item-list))
+           item-list)))
+
+  (define (add-fretstring-fret-offset fret-offset fretstring-list)
+    (map (lambda (x) (add-item-fret-offset fret-offset x))
+         fretstring-list))
+
+  (define (add-terse-fret-offset fret-offset terse-string-list)
+    (map (lambda (x) (add-fretstring-fret-offset fret-offset x))
+         terse-string-list))
+
+;; body
+  (join-terse-string
+    (add-terse-fret-offset
+      fret-offset
+      (split-terse-string terse-string))))
+
diff --git a/scm/song-util.scm b/scm/song-util.scm
index 22e5d83bd9..2453a14ed3 100644
--- a/scm/song-util.scm
+++ b/scm/song-util.scm
@@ -116,15 +116,6 @@
   `(set! ,list-var (append ,list-var (list ,object))))
 (export add!)
 
-(define-public (flatten lst)
-  (cond
-   ((null? lst)
-    lst)
-   ((pair? (car lst))
-    (append (flatten (car lst)) (flatten (cdr lst))))
-   (else
-    (cons (car lst) (flatten (cdr lst))))))
-
 (define-public (safe-car list)
   (if (null? list)
       #f
diff --git a/scm/stencil.scm b/scm/stencil.scm
index fb46ef7251..6a4b88d7b2 100644
--- a/scm/stencil.scm
+++ b/scm/stencil.scm
@@ -94,8 +94,8 @@ encloses the contents.
 "
   (let* ((xext (ly:grob-extent grob grob 0))
 	 (yext (ly:grob-extent grob grob 1))
-	 (thick 0.1))
-    
+	 (thick 0.01))
+
     (ly:stencil-add
      (make-filled-box-stencil xext (cons (- (car yext) thick) (car yext)))
      (make-filled-box-stencil xext (cons (cdr yext) (+ (cdr yext) thick)))
diff --git a/scm/translation-functions.scm b/scm/translation-functions.scm
index 667b0e2679..d4c84caf61 100644
--- a/scm/translation-functions.scm
+++ b/scm/translation-functions.scm
@@ -168,26 +168,68 @@
 ;; fret diagrams
 
 (define-public (determine-frets context grob notes string-numbers)
+  
   (define (ensure-number a b)
     (if (number? a)
 	a
 	b))
-(let*
+
+  (define (string-frets->dot-placement string-frets string-count)
+    (let*
+      ((desc (list->vector
+              (map (lambda (x) (list 'mute  (1+ x)))
+                   (iota string-count)))))
+
+       (for-each (lambda (sf)
+                   (let*
+                       ((string (car sf))
+                        (fret (cadr sf))
+                        (finger (caddr sf)))
+
+                       (vector-set! 
+                         desc (1- string)
+                         (if (= 0 fret)
+                             (list 'open string)
+                             (if finger
+                                 (list 'place-fret string fret finger)
+                                 (list 'place-fret string fret))
+                                      ))
+                     ))
+                 string-frets)
+       (vector->list desc)))
+
+;; body.
+  (let*
       ((tunings (ly:context-property context 'stringTunings))
+       (my-string-count (length tunings))
        (details (ly:grob-property grob 'fret-diagram-details))
+       (predefined-frets
+         (ly:context-property context 'predefinedDiagramTable)) 
        (minimum-fret (ensure-number
 		      (ly:context-property context 'minimumFret) 0))
        (max-stretch (ensure-number
 		      (ly:context-property context 'maximumFretStretch) 4))
        (string-frets (determine-frets-mf notes string-numbers
 					 minimum-fret max-stretch
-					 tunings)))
+					 tunings))
+       (pitches (map (lambda (x) (ly:event-property x 'pitch)) notes)))
+
+    (set! (ly:grob-property grob 'fret-diagram-details)
 
-  (set! (ly:grob-property grob 'fret-diagram-details)
           (if (null? details)
               (acons 'string-count (length tunings) '())
               (acons 'string-count (length tunings) details)))
-  (set! (ly:grob-property grob 'string-fret-finger-combinations) string-frets)))
+    (set! (ly:grob-property grob 'dot-placement-list)
+        (if predefined-frets
+            (let ((hash-handle 
+                    (hash-get-handle
+                      predefined-frets
+                      (cons tunings pitches))))
+              (if hash-handle 
+                  (cdr hash-handle)  ;found default diagram
+                  (string-frets->dot-placement 
+                        string-frets my-string-count)))
+            (string-frets->dot-placement string-frets my-string-count)))))
 
 (define-public (determine-frets-mf notes string-numbers
 				   minimum-fret max-stretch
diff --git a/scripts/abc2ly.py b/scripts/abc2ly.py
index 05edf98ae5..be84071e9f 100644
--- a/scripts/abc2ly.py
+++ b/scripts/abc2ly.py
@@ -1341,7 +1341,8 @@ def print_version ():
 def get_option_parser ():
     p = ly.get_option_parser (usage=_ ("%s [OPTION]... FILE") % 'abc2ly',
                  description=_ ('''abc2ly converts ABC music files (see
-%s) to LilyPond input.''') % 'http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt',
+%s) to LilyPond input.
+''') % 'http://www.gre.ac.uk/~c.walshaw/abc2mtex/abc.txt',
                  add_help_option=False)
 
     p.version = "abc2ly (LilyPond) @TOPLEVEL_VERSION@"
@@ -1358,7 +1359,7 @@ def get_option_parser ():
     p.add_option ('-s', '--strict', help=_ ("be strict about success"),
                   action='store_true')
     p.add_option ('-b', '--beams', help=_ ("preserve ABC's notion of beams"))
-    p.add_option_group (ly.display_encode (_ ('Bugs')),
+    p.add_option_group ('',
                         description=(_ ('Report bugs via')
                                      + ''' http://post.gmane.org/post.php'''
                                      '''?group=gmane.comp.gnu.lilypond.bugs\n'''))
diff --git a/scripts/convert-ly.py b/scripts/convert-ly.py
index 708214d315..9bc0a14005 100644
--- a/scripts/convert-ly.py
+++ b/scripts/convert-ly.py
@@ -32,8 +32,8 @@ _ ('''Update LilyPond input to newer version.  By default, update from the
 version taken from the \\version command, to the current LilyPond version.''')
 + _ ("Examples:")
 + '''
-  convert-ly -e old.ly
-  convert-ly --from=2.3.28 --to 2.5.21 foobar.ly
+  $ convert-ly -e old.ly
+  $ convert-ly --from=2.3.28 --to=2.5.21 foobar.ly > foobar-new.ly
 ''')
 
 copyright = ('Jan Nieuwenhuizen <janneke@gnu.org>',
@@ -105,7 +105,7 @@ def get_option_parser ():
               default=False)
     
     p.add_option ("-s", '--show-rules',
-              help=_ ("show rules [default: --from=0, --to=%s]") % program_version,
+              help=_ ("show rules [default: -f 0, -t %s]") % program_version,
               dest='show_rules',
               action='store_true', default=False)
     
@@ -116,7 +116,7 @@ def get_option_parser ():
               dest="to_version",
               default='')
 
-    p.add_option_group (ly.display_encode (_ ('Bugs')),
+    p.add_option_group ('',
                         description=(_ ("Report bugs via")
                                      + ''' http://post.gmane.org/post.php'''
                                      '''?group=gmane.comp.gnu.lilypond.bugs\n'''))
diff --git a/scripts/etf2ly.py b/scripts/etf2ly.py
index 5377727d80..39a6fba4ab 100644
--- a/scripts/etf2ly.py
+++ b/scripts/etf2ly.py
@@ -1178,7 +1178,8 @@ Copyright (c) %s by
 def get_option_parser ():
     p = ly.get_option_parser (usage=_ ("%s [OPTION]... ETF-FILE") % 'etf2ly',
                  description=_ ("""Enigma Transport Format is a format used by Coda Music Technology's
-Finale product.  etf2ly converts a subset of ETF to a ready-to-use LilyPond file."""),
+Finale product.  etf2ly converts a subset of ETF to a ready-to-use LilyPond file.
+"""),
                  add_help_option=False)
     p.add_option("-h", "--help",
                  action="help",
@@ -1194,7 +1195,7 @@ Finale product.  etf2ly converts a subset of ETF to a ready-to-use LilyPond file
            action='store_true',
            ),
 
-    p.add_option_group (ly.display_encode (_ ('Bugs')),
+    p.add_option_group ('',
                         description=(_ ('Report bugs via')
                                      + ''' http://post.gmane.org/post.php'''
                                      '''?group=gmane.comp.gnu.lilypond.bugs\n'''))
diff --git a/scripts/lilymidi.py b/scripts/lilymidi.py
old mode 100755
new mode 100644
diff --git a/scripts/lilypond-book.py b/scripts/lilypond-book.py
index 630f6067de..1f925c13bd 100644
--- a/scripts/lilypond-book.py
+++ b/scripts/lilypond-book.py
@@ -58,9 +58,9 @@ _ ("Process LilyPond snippets in hybrid HTML, LaTeX, texinfo or DocBook document
 + '\n\n'
 + _ ("Examples:")
 + '''
- lilypond-book --filter="tr '[a-z]' '[A-Z]'" %(BOOK)s
- lilypond-book --filter="convert-ly --no-version --from=2.0.0 -" %(BOOK)s
- lilypond-book --process='lilypond -I include' %(BOOK)s
+ $ lilypond-book --filter="tr '[a-z]' '[A-Z]'" %(BOOK)s
+ $ lilypond-book -F "convert-ly --no-version --from=2.0.0 -" %(BOOK)s
+ $ lilypond-book --process='lilypond -I include' %(BOOK)s
 ''' % {'BOOK': _ ("BOOK")})
 
 authors = ('Jan Nieuwenhuizen <janneke@gnu.org>',
@@ -113,11 +113,12 @@ def get_option_parser ():
     p.add_option ('-F', '--filter', metavar=_ ("FILTER"),
                   action="store",
                   dest="filter_cmd",
-                  help=_ ("pipe snippets through FILTER [convert-ly -n -]"),
+                  help=_ ("pipe snippets through FILTER [default: `convert-ly -n -']"),
                   default=None)
 
     p.add_option ('-f', '--format',
                   help=_ ("use output format FORMAT (texi [default], texi-html, latex, html, docbook)"),
+                  metavar=_ ("FORMAT"),
                   action='store')
 
     p.add_option("-h", "--help",
@@ -155,7 +156,7 @@ def get_option_parser ():
                   default='')
     
     p.add_option ('--skip-lily-check',
-                  help=_ ("do not fail if no lilypond output is found."),
+                  help=_ ("do not fail if no lilypond output is found"),
                   metavar=_ ("DIR"),
                   action='store_true', dest='skip_lilypond_run',
                   default=False)
@@ -167,7 +168,7 @@ def get_option_parser ():
                   default=False)
     
     p.add_option ('--lily-output-dir',
-                  help=_ ("write lily-XXX files to DIR, link into --output dir."),
+                  help=_ ("write lily-XXX files to DIR, link into --output dir"),
                   metavar=_ ("DIR"),
                   action='store', dest='lily_output_dir',
                   default=None)
@@ -196,7 +197,7 @@ def get_option_parser ():
     p.add_option ('-w', '--warranty',
                   help=_ ("show warranty and copyright"),
                   action='store_true')
-    p.add_option_group (ly.display_encode (_ ('Bugs')),
+    p.add_option_group ('',
                         description=(
         _ ("Report bugs via")
         + ' http://post.gmane.org/post.php?group=gmane.comp.gnu.lilypond.bugs\n'))
diff --git a/scripts/lilysong.py b/scripts/lilysong.py
old mode 100755
new mode 100644
index 18d047a137..adc6f57526
--- a/scripts/lilysong.py
+++ b/scripts/lilysong.py
@@ -36,14 +36,14 @@ import tempfile
 FESTIVAL_COMMAND = 'festival --pipe'
 VOICE_CODINGS = {'voice_czech_ph': 'iso-8859-2'}
 
-_USAGE = """lilysong [ -p PLAY-PROGRAM ] FILE.xml [ LANGUAGE-CODE-OR-VOICE [ SPEEDUP ] ]
-./lilysong FILE.ly [ LANGUAGE-CODE-OR-VOICE ]
-./lilysong --list-voices
-./lilysong --list-languages
+_USAGE = """lilysong [-p PLAY-PROGRAM] FILE.xml [LANGUAGE-CODE-OR-VOICE [SPEEDUP]]
+       lilysong FILE.ly [LANGUAGE-CODE-OR-VOICE]
+       lilysong --list-voices
+       lilysong --list-languages
 """
 
 def usage ():
-    print 'usage:', _USAGE
+    print 'Usage:', _USAGE
     sys.exit (2)
 
 def process_options (args):
diff --git a/scripts/midi2ly.py b/scripts/midi2ly.py
index 4b5f2507aa..6ddc78ae71 100644
--- a/scripts/midi2ly.py
+++ b/scripts/midi2ly.py
@@ -844,7 +844,7 @@ def convert_midi (in_file, out_file):
 
 def get_option_parser ():
     p = ly.get_option_parser (usage=_ ("%s [OPTION]... FILE") % 'midi2ly',
-                 description=_ ("Convert %s to LilyPond input.") % 'MIDI',
+                 description=_ ("Convert %s to LilyPond input.\n") % 'MIDI',
                  add_help_option=False)
 
     p.add_option ('-a', '--absolute-pitches',
@@ -888,10 +888,9 @@ def get_option_parser ():
 
     p.add_option_group (ly.display_encode (_ ("Examples")),
               description = r'''
-  midi2ly --key=-2:1 --duration-quant=32 \
-    --allow-tuplet=4*2/3 --allow-tuplet=2*4/3 foo.midi
+  $ midi2ly --key=-2:1 --duration-quant=32 --allow-tuplet=4*2/3 --allow-tuplet=2*4/3 foo.midi
 ''')
-    p.add_option_group (ly.display_encode (_ ('Bugs')),
+    p.add_option_group ('',
                         description=(_ ('Report bugs via')
                                      + ''' http://post.gmane.org/post.php'''
                                      '''?group=gmane.comp.gnu.lilypond.bugs\n'''))
diff --git a/scripts/musicxml2ly.py b/scripts/musicxml2ly.py
index c6e7dd53c2..886479a893 100644
--- a/scripts/musicxml2ly.py
+++ b/scripts/musicxml2ly.py
@@ -2141,26 +2141,30 @@ def get_all_voices (parts):
 
 
 def option_parser ():
-    p = ly.get_option_parser (usage = _ ("musicxml2ly [options] FILE.xml"),
-                             description = _ ("Convert MusicXML from FILE.xml to LilyPond input. If the given filename is -, musicxml2ly reads from the command line.") + "\n",
-                             add_help_option=False)
+    p = ly.get_option_parser (usage = _ ("musicxml2ly [OPTION]... FILE.xml"),
+                             description =
+_ ("""Convert MusicXML from FILE.xml to LilyPond input.
+If the given filename is -, musicxml2ly reads from the command line.
+"""), add_help_option=False)
 
     p.add_option("-h", "--help",
                  action="help",
                  help=_ ("show this help and exit"))
 
     p.version = ('''%prog (LilyPond) @TOPLEVEL_VERSION@\n\n'''
-                                      +
-_ ("""This program is free software.  It is covered by the GNU General Public
-License and you are welcome to change it and/or distribute copies of it
-under certain conditions.  Invoke as `%s --warranty' for more
-information.""") % 'lilypond'
-+ """
-Copyright (c) 2005--2008 by
++
+_ ("""Copyright (c) 2005--2008 by
     Han-Wen Nienhuys <hanwen@xs4all.nl>,
     Jan Nieuwenhuizen <janneke@gnu.org> and
     Reinhold Kainhofer <reinhold@kainhofer.com>
-""")
+"""
++
+"""
+This program is free software.  It is covered by the GNU General Public
+License and you are welcome to change it and/or distribute copies of it
+under certain conditions.  Invoke as `%s --warranty' for more
+information.""") % 'lilypond')
+
     p.add_option("--version",
                  action="version",
                  help=_ ("show version number and exit"))
@@ -2217,7 +2221,7 @@ Copyright (c) 2005--2008 by
                   type = 'string',
                   dest = 'output_name',
                   help = _ ("set output filename to FILE, stdout if -"))
-    p.add_option_group (ly.display_encode (_ ('Bugs')),
+    p.add_option_group ('',
                         description = (_ ("Report bugs via")
                                      + ''' http://post.gmane.org/post.php'''
                                      '''?group=gmane.comp.gnu.lilypond.bugs\n'''))