X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finstrument-notation.itely;h=e7e1b1aa899a9d1e2d46f6fe0ab1be620edb7694;hb=cc4370c05c005e07a81ab6ec2ec8657a6d361787;hp=bed34c62f509c1a69d7fdf47060b3e48121599ea;hpb=c2389d605aaaf3b3e8c416428d4b4088e4b049ca;p=lilypond.git

diff --git a/Documentation/user/instrument-notation.itely b/Documentation/user/instrument-notation.itely
index bed34c62f5..cd8f1e473a 100644
--- a/Documentation/user/instrument-notation.itely
+++ b/Documentation/user/instrument-notation.itely
@@ -1,7 +1,14 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
 @c This file is part of lilypond.tely
+@ignore
+    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+    When revising a translation, copy the HEAD committish of the
+    version that you are working on.  See TRANSLATION for details.
+@end ignore
 
-@c A menu is needed before every deeper *section nesting of @node's; run 
+
+@c A menu is needed before every deeper *section nesting of @node's; run
 @c     M-x texinfo-all-menus-update
 @c to automatically fill in these menus before saving changes
 
@@ -36,7 +43,6 @@ handle this cross-staffing behavior.  In this section we discuss the
 @menu
 * Automatic staff changes::     
 * Manual staff switches::       
-* Laissez vibrer ties::         
 * Pedals::                      
 * Staff switch lines::          
 * Cross staff stems::           
@@ -45,17 +51,12 @@ handle this cross-staffing behavior.  In this section we discuss the
 @refbugs
 
 Dynamics are not centered, but workarounds do exist.  See the
-``piano centered dynamics'' template in @ref{Piano templates}.
+@q{piano centered dynamics} template in @ref{Piano templates}.
 
 @cindex cross staff stem
 @cindex stem, cross staff
 @cindex distance between staves in piano music
 
-The distance between the two staves is the same for all systems in the
-score.  It is possible to override this per system, but it does require
-an arcane command incantation.  See
-@inputfileref{input/@/test,piano@/-staff@/-distance@/.ly}.
-
 
 @node Automatic staff changes
 @subsection Automatic staff changes
@@ -90,8 +91,8 @@ The autochanger switches on basis of the pitch (middle C is the turning
 point), and it looks ahead skipping over rests to switch in
 advance.  Here is a practical example
 
-@lilypond[quote,verbatim,raggedright]
-\context PianoStaff
+@lilypond[quote,verbatim,ragged-right]
+\new PianoStaff
   \autochange \relative c'
   {
     g4 a b c d r4 a g
@@ -136,10 +137,10 @@ usually the setup for a score will start with a setup of the staves,
 
 @example
 <<
-  \context Staff = up @{
+  \new Staff = "up" @{
     \skip 1 * 10  % @emph{keep staff alive}
     @}
-  \context Staff = down @{
+  \new Staff = "down" @{
     \skip 1 * 10  % @emph{idem}
     @}
 >>
@@ -154,28 +155,6 @@ and the @context{Voice} is inserted afterwards
 @end example
 
 
-@node Laissez vibrer ties
-@subsection Laissez vibrer ties
-@cindex Laissez vibrer
-@cindex Ties,  laissez vibrer
-
-L.v. ties (laissez vibrer) indicate that notes must not be damped at the
-end. It is used in notation for piano, harp and other string and
-percussion instruments. They can be entered using @code{\laissezVibrer},
-
-@lilypond[fragment,raggedright,verbatim,relative=1]
-<c f g>\laissezVibrer 
-@end lilypond
-
-@seealso
-
-Program reference: 
-@internalsref{LaissezVibrerTie}
-@internalsref{LaissezVibrerTieColumn}
-
-Example files:
-@inputfileref{input/regression,laissez-vibrer-tie.ly}
-
 @node Pedals
 @subsection Pedals
 @cindex Pedals
@@ -189,7 +168,7 @@ Piano pedal instruction can be expressed by attaching
 @code{\treCorde}, @code{\sostenutoDown} and @code{\sostenutoUp} to a
 note or chord
 
-@lilypond[quote,raggedright,fragment,verbatim]
+@lilypond[quote,ragged-right,fragment,verbatim]
 c'4\sustainDown c'4\sustainUp
 @end lilypond
 
@@ -202,7 +181,7 @@ information.
 Pedals can also be indicated by a sequence of brackets, by setting the
 @code{pedalSustainStyle} property to bracket objects
 
-@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 \set Staff.pedalSustainStyle = #'bracket
 c\sustainDown d e
 b\sustainUp\sustainDown
@@ -213,18 +192,18 @@ A third style of pedal notation is a mixture of text and brackets,
 obtained by setting the @code{pedalSustainStyle} property to
 @code{mixed}
 
-@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 \set Staff.pedalSustainStyle = #'mixed
 c\sustainDown d e
 b\sustainUp\sustainDown
 b g \sustainUp a \sustainDown \bar "|."
 @end lilypond
 
-The default `*Ped.' style for sustain and damper pedals corresponds to
+The default @q{*Ped.} style for sustain and damper pedals corresponds to
 style @code{#'text}.  The sostenuto pedal uses @code{mixed} style by
 default.
 
-@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 c\sostenutoDown d e c, f g a\sostenutoUp
 @end lilypond
 
@@ -235,14 +214,14 @@ For fine-tuning the appearance of a pedal bracket, the properties
 modified.  For example, the bracket may be extended to the right edge
 of the note head
 
-@lilypond[quote,raggedright,fragment,verbatim,relative=2]
+@lilypond[quote,ragged-right,fragment,verbatim,relative=2]
 \override Staff.PianoPedalBracket #'shorten-pair = #'(0 . -1.0)
 c\sostenutoDown d e c, f g a\sostenutoUp
 @end lilypond
 
 @seealso
 
-In this manual: @ref{Laissez vibrer ties}
+In this manual: @ref{Laissez vibrer ties}.
 
 @node Staff switch lines
 @subsection Staff switch lines
@@ -252,21 +231,21 @@ In this manual: @ref{Laissez vibrer ties}
 @cindex staff switching
 @cindex cross staff
 
-@cindex @code{followVoice}
+@funindex followVoice
 
 Whenever a voice switches to another staff, a line connecting the notes
 can be printed automatically.  This is switched on by setting
 @code{followVoice} to true
 
-@lilypond[quote,raggedright,fragment,relative=1,verbatim]
+@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
 \new PianoStaff <<
-  \context Staff=one {
+  \new Staff="one" {
     \set followVoice = ##t
     c1
     \change Staff=two
     b2 a
   }
-  \context Staff=two { \clef bass \skip 1*2 }
+  \new Staff="two" { \clef bass \skip 1*2 }
 >>
 @end lilypond
 
@@ -276,9 +255,9 @@ Program reference: @internalsref{VoiceFollower}.
 
 @refcommands
 
-@cindex @code{\showStaffSwitch}
+@funindex \showStaffSwitch
 @code{\showStaffSwitch},
-@cindex @code{\hideStaffSwitch}
+@funindex \hideStaffSwitch
 @code{\hideStaffSwitch}.
 
 
@@ -289,10 +268,13 @@ Chords that cross staves may be produced by increasing the length
 of the stem in the lower staff, so it reaches the stem in the upper
 staff, or vice versa.
 
-@lilypond[raggedright,verbatim,quote]
-stemExtend = \once \override Stem #'length = #22
+@lilypond[ragged-right,verbatim,quote]
+stemExtend = {
+  \once \override Stem #'length = #10
+  \once \override Stem #'cross-staff = ##t
+}
 noFlag = \once \override Stem #'flag-style = #'no-flag
-\context PianoStaff <<
+\new PianoStaff <<
   \new Staff {
     \stemDown \stemExtend
     f'4
@@ -330,7 +312,7 @@ entered by name.  Internally, the chords are represented as a set of
 pitches, so they can be transposed
 
 
-@lilypond[quote,raggedright,verbatim,raggedright]
+@lilypond[quote,ragged-right,verbatim,ragged-right]
 twoWays = \transpose c c' {
   \chordmode {
     c1 f:sus4 bes/f
@@ -340,8 +322,8 @@ twoWays = \transpose c c' {
   <f bes d'>
 }
 
-<< \context ChordNames \twoWays
-   \context Voice \twoWays >>
+<< \new ChordNames \twoWays
+   \new Voice \twoWays >>
 @end lilypond
 
 This example also shows that the chord printing routines do not try to
@@ -364,7 +346,7 @@ In chord mode sets of pitches (chords) are entered with normal note
 names.  A chord is entered by the root, which is entered like a
 normal pitch
 
-@lilypond[quote,raggedright,fragment,verbatim]
+@lilypond[quote,ragged-right,fragment,verbatim]
 \chordmode { es4. d8 c2 }
 @end lilypond
 
@@ -376,14 +358,17 @@ The mode is introduced by the keyword @code{\chordmode}.
 
 Other chords may be entered by suffixing a colon and introducing a
 modifier (which may include a number if desired)
+
 @lilypond[quote,fragment,verbatim]
 \chordmode { e1:m e1:7 e1:m7 }
 @end lilypond
-The first number following the root is taken to be the `type' of the
+
+The first number following the root is taken to be the @q{type} of the
 chord, thirds are added to the root until it reaches the specified
-number
+number.  The exception is @code{c:13}, for which the 11 is omitted.
+
 @lilypond[quote,fragment,verbatim]
-\chordmode { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 }
+\chordmode { c:3 c:5 c:6 c:7 c:8 c:9 c:10 c:11 c:13 }
 @end lilypond
 
 @cindex root of chord
@@ -393,16 +378,21 @@ number
 More complex chords may also be constructed adding separate steps
 to a chord.  Additions are added after the number following
 the colon and are separated by dots
+
 @lilypond[quote,verbatim,fragment]
 \chordmode { c:5.6 c:3.7.8 c:3.6.13 }
 @end lilypond
+
 Chord steps can be altered by suffixing a @code{-} or @code{+} sign
 to the number
+
 @lilypond[quote,verbatim,fragment]
 \chordmode { c:7+ c:5+.3- c:3-.5-.7- }
 @end lilypond
+
 Removals are specified similarly and are introduced by a caret.  They
 must come after the additions
+
 @lilypond[quote,verbatim,fragment]
 \chordmode { c^3 c:7^5 c:9^3.5 }
 @end lilypond
@@ -436,33 +426,33 @@ Modifiers can be mixed with additions
 @end lilypond
 
 @cindex modifiers, in chords.
-@cindex @code{aug}
-@cindex @code{dim}
-@cindex @code{maj}
-@cindex @code{sus}
-@cindex @code{m}
+@funindex aug
+@funindex dim
+@funindex maj
+@funindex sus
+@funindex m
 
 Since an unaltered 11 does not sound good when combined with an
-unaltered 3, the 11 is removed in this case (unless it is added
+unaltered 13, the 11 is removed in this case (unless it is added
 explicitly)
-@lilypond[quote,raggedright,fragment,verbatim]
+@lilypond[quote,ragged-right,fragment,verbatim]
 \chordmode { c:13 c:13.11 c:m13 }
 @end lilypond
 
-@cindex @code{/}
+@funindex /
 
 An inversion (putting one pitch of the chord on the bottom), as well
 as bass notes, can be specified by appending
 @code{/}@var{pitch} to the chord
-@lilypond[quote,raggedright,fragment,verbatim]
+@lilypond[quote,ragged-right,fragment,verbatim]
 \chordmode { c1 c/g c/f }
 @end lilypond
-@cindex @code{/+}
+@funindex /+
 
-A bass note can be added instead transposed out of the chord,
+A bass note can be added instead of transposed out of the chord,
 by using @code{/+}@var{pitch}.
 
-@lilypond[quote,raggedright,fragment,verbatim]
+@lilypond[quote,ragged-right,fragment,verbatim]
 \chordmode { c1 c/+g c/+f }
 @end lilypond
 
@@ -479,7 +469,7 @@ Each step can only be present in a chord once.  The following
 simply produces the augmented chord, since @code{5+} is interpreted
 last
 @cindex clusters
-@lilypond[quote,raggedright,verbatim,fragment]
+@lilypond[quote,ragged-right,verbatim,fragment]
 \chordmode { c:5.5-.5+ }
 @end lilypond
 
@@ -495,13 +485,13 @@ For displaying printed chord names, use the @internalsref{ChordNames} context.
 The chords may be entered either using the notation
 described above, or directly using @code{<} and @code{>}
 
-@lilypond[quote,verbatim,raggedright]
+@lilypond[quote,verbatim,ragged-right]
 harmonies = {
   \chordmode {a1 b c} <d' f' a'> <e' g' b'>
 }
 <<
-  \context ChordNames \harmonies
-  \context Staff \harmonies
+  \new ChordNames \harmonies
+  \new Staff \harmonies
 >>
 @end lilypond
 
@@ -510,15 +500,15 @@ You can make the chord changes stand out by setting
 display chord names when there is a change in the chords scheme and at
 the start of a new line
 
-@lilypond[quote,verbatim,raggedright]
+@lilypond[quote,verbatim,ragged-right]
 harmonies = \chordmode {
   c1:m c:m \break c:m c:m d
 }
 <<
-  \context ChordNames {
+  \new ChordNames {
     \set chordChanges = ##t
     \harmonies }
-  \context Staff \transpose c c' \harmonies
+  \new Staff \transpose c c' \harmonies
 >>
 @end lilypond
 
@@ -527,19 +517,19 @@ necessary.  Chords may also be printed separately.  It may be necessary
 to add @internalsref{Volta_engraver} and @internalsref{Bar_engraver}
 for showing repeats.
 
-@lilypond[raggedright,verbatim]
+@lilypond[ragged-right,verbatim]
 \new ChordNames \with {
   \override BarLine #'bar-size = #4
-  voltaOnThisStaff = ##t
   \consists Bar_engraver
   \consists "Volta_engraver"
 }
-\repeat volta 2 \chordmode {
-  f1:maj f:7 bes:7
-  c:maj
+\chordmode { \repeat volta 2 {
+  f1:maj7 f:7 bes:7
+  c:maj7
 } \alternative {
   es e
 }
+}
 @end lilypond
 
 
@@ -548,7 +538,7 @@ Klaus Ignatzek (see @ref{Literature list}).  It can be tuned through the
 following properties
 
 @table @code
-@cindex @code{chordNameExceptions}
+@funindex chordNameExceptions
 @item chordNameExceptions
 This is a list that contains the chords that have special formatting.
 
@@ -573,24 +563,24 @@ adds the new exceptions to the default ones, which are defined in
 @file{ly/@/chord@/-modifier@/-init@/.ly}.
 
 For an example of tuning this property, see also
-@inputfileref{input/@/regression,chord@/-name@/-exceptions@/.ly}.
+@lsr{chords,chord@/-name@/-exceptions@/.ly}
 @cindex exceptions, chord names.
 
 
-@cindex @code{majorSevenSymbol}
+@funindex majorSevenSymbol
 @item majorSevenSymbol
 This property contains the markup object used for the 7th step, when
 it is major.  Predefined options are @code{whiteTriangleMarkup} and
 @code{blackTriangleMarkup}.  See
-@inputfileref{input/@/regression,chord@/-name@/-major7@/.ly} for an example.
+@lsr{chords,chord@/-name@/-major7@/.ly} for an example.
 
-@cindex @code{chordNameSeparator}
+@funindex chordNameSeparator
 @item chordNameSeparator
 Different parts of a chord name are normally separated by a
 slash.  By setting @code{chordNameSeparator}, you can specify other
 separators, e.g.,
-@lilypond[quote,raggedright,fragment,verbatim]
-\context ChordNames \chordmode {
+@lilypond[quote,ragged-right,fragment,verbatim]
+\new ChordNames \chordmode {
   c:7sus4
   \set chordNameSeparator
     = \markup { \typewriter "|" }
@@ -598,41 +588,41 @@ separators, e.g.,
 }
 @end lilypond
 
-@cindex @code{chordRootNamer}
+@funindex chordRootNamer
 @item chordRootNamer
 The root of a chord is usually printed as a letter with an optional
 alteration.  The transformation from pitch to letter is done by this
-function.  Special note names (for example, the German ``H'' for a
+function.  Special note names (for example, the German @q{H} for a
 B-chord) can be produced by storing a new function in this property.
 
-@cindex @code{chordNoteNamer}
+@funindex chordNoteNamer
 @item chordNoteNamer
 The default is to print single pitch, e.g., the bass note, using the
 @code{chordRootNamer}.  The @code{chordNoteNamer} property can be set
 to a specialized function to change this behavior.  For example, the
 base can be printed in lower case.
 
-@cindex @code{chordPrefixSpacer}
+@funindex chordPrefixSpacer
 @item chordPrefixSpacer
-The ``m'' for minor chords is usually printed right after the root of 
-the chord. By setting @code{chordPrefixSpacer}, you can fix a spacer 
-between the root and ``m''. The spacer is not used when the root
+The @q{m} for minor chords is usually printed right after the root of
+the chord. By setting @code{chordPrefixSpacer}, you can fix a spacer
+between the root and @q{m}. The spacer is not used when the root
 is altered.
 
 @end table
 
 The predefined variables @code{\germanChords},
-@code{\semiGermanChords}, @code{\italianChords} and @code{\frenchChords} 
+@code{\semiGermanChords}, @code{\italianChords} and @code{\frenchChords}
 set these variables.  The effect is
 demonstrated here,
 
-@lilypondfile[raggedright]{chord-names-languages.ly}
+@lilypondfile[ragged-right]{chord-names-languages.ly}
 
 There are also two other chord name schemes implemented: an alternate
 Jazz chord notation, and a systematic scheme called Banter chords.  The
 alternate Jazz notation is also shown on the chart in @ref{Chord name
-chart}.  Turning on these styles is described in the input file
-@inputfileref{input/@/test,chord@/-names@/-jazz@/.ly}.
+chart}.  Turning on these styles is demonstrated in
+@lsr{chords,chord-names-jazz.ly}.
 
 @cindex Banter
 @cindex jazz chords
@@ -641,13 +631,13 @@ chart}.  Turning on these styles is described in the input file
 
 @refcommands
 
-@cindex @code{\germanChords}
+@funindex \germanChords
 @code{\germanChords},
-@cindex @code{\semiGermanChords}
+@funindex \semiGermanChords
 @code{\semiGermanChords}.
-@cindex @code{\italianChords}
+@funindex \italianChords
 @code{\italianChords}.
-@cindex @code{\frenchChords}
+@funindex \frenchChords
 @code{\frenchChords}.
 
 
@@ -655,10 +645,8 @@ chart}.  Turning on these styles is described in the input file
 
 @seealso
 
-Examples: @inputfileref{input/@/regression,chord@/-name@/-major7@/.ly},
-@inputfileref{input/@/regression,chord@/-name@/-exceptions@/.ly},
-@inputfileref{input/@/test,chord@/-names@/-jazz@/.ly}.
-
+Examples:
+@lsrdir{chords}
 
 Init files: @file{scm/@/chords@/-ignatzek@/.scm}, and
 @file{scm/@/chord@/-entry@/.scm}.
@@ -676,7 +664,8 @@ may result in strange chord names when chords are entered with the
 @node Vocal music
 @section Vocal music
 
-There are three different issues when printing vocal music
+Since LilyPond input files are text, there are two issues to
+consider when working with vocal music:
 
 @itemize @bullet
 @item
@@ -684,35 +673,56 @@ Song texts must be entered as text, not notes.  For example, the
 input@tie{}@code{d} should be interpreted as a one letter syllable, not the
 note@tie{}D.
 
-@item
-Song texts must be printed as text, not as notes.
-
 @item
 Song texts must be aligned with the notes of their melody.
 @end itemize
 
-The simplest solution for printing music uses the @code{\addlyrics}
-function to solve all these problems at once.  However, these
-three functions can be controlled separately, which is necessary
-for complex vocal music.
-
+There are a few different ways to define lyrics; we shall begin
+by examining the simplest method, and gradually increase complexity.
 
 @menu
 * Setting simple songs::        
 * Entering lyrics::             
-* Hyphens and extenders::       
-* The Lyrics context::          
-* Flexibility in alignment::    
-* More stanzas::                
+* Aligning lyrics to a melody::  
+* Working with lyrics and identifiers::  
+* Flexibility in placement::    
+* Spacing lyrics::              
+* More about stanzas::          
 * Ambitus::                     
 * Other vocal issues::          
 @end menu
 
+
+@commonprop
+
+Checking to make sure that text scripts and lyrics are within the margins is
+a relatively large computational task.  To speed up processing, lilypond does
+not perform such calculations by default; to enable it, use
+
+@example
+\override Score.PaperColumn #'keep-inside-line = ##t
+@end example
+
+To make lyrics avoid barlines as well, use
+@example
+\layout @{
+  \context @{
+    \Lyrics
+      \consists "Bar_engraver"
+      \consists "Separating_line_group_engraver"
+      \override BarLine #'transparent = ##t
+  @}
+@}
+@end example
+
+
 @node Setting simple songs
 @subsection Setting simple songs
 
-The easiest way to add lyrics to a melody is to append
 @cindex \addlyrics
+
+The easiest way to add lyrics to a melody is to append
+
 @example
 \addlyrics @{ @var{the lyrics} @}
 @end example
@@ -720,7 +730,7 @@ The easiest way to add lyrics to a melody is to append
 @noindent
 to a melody.  Here is an example,
 
-@lilypond[raggedright,verbatim,fragment,quote]
+@lilypond[ragged-right,verbatim,fragment,quote]
 \time 3/4
 \relative { c2 e4 g2. }
 \addlyrics { play the game }
@@ -729,7 +739,7 @@ to a melody.  Here is an example,
 More stanzas can be added by adding more
 @code{\addlyrics} sections
 
-@lilypond[raggedright,verbatim,fragment,quote]
+@lilypond[ragged-right,verbatim,fragment,quote]
 \time 3/4
 \relative { c2 e4 g2. }
 \addlyrics { play the game }
@@ -737,91 +747,115 @@ More stanzas can be added by adding more
 \addlyrics { joue le jeu }
 @end lilypond
 
-@c TODO - this isn't such a great place for this note, but I can't
-@c  find a better place without rearranging a lot of lyric stuff.
-@c  It's yet another thing to look at post-3.0.
-
-The @code{\addlyrics} command is actually just a convienient way
-to write a more complicated LilyPond structure that sets up the
-lyrics.  You should use @code{\addlyrics} unless you need to do
-fancy things, in which case you should investigate
-@code{\lyricsto} or @code{\lyricmode}.
-
-@example
-@{ MUSIC @}
-\addlyrics @{ LYRICS @}
-@end example
-
-@noindent
-is the same as
-
-@example
-\context Voice = blah @{ music @}
-\lyricsto "blah" \new lyrics @{ LYRICS @}
-@end example
+The command @code{\addlyrics} cannot handle polyphony settings.  For these
+cases you should use @code{\lyricsto} and @code{\lyricmode}, as will be
+introduced in @ref{Entering lyrics}.
 
-@refbugs
-
-@code{\addlyrics} cannot handle polyphony.
 
 
 @node Entering lyrics
 @subsection Entering lyrics
 
 @cindex lyrics
-@cindex @code{\lyricmode}
+@funindex \lyricmode
 @cindex punctuation
+@cindex spaces, in lyrics
+@cindex quotes, in lyrics
 
-Lyrics are entered in a special input mode.  This mode is introduced
+Lyrics are entered in a special input mode, which can be introduced
 by the keyword @code{\lyricmode}, or by using @code{\addlyrics} or
 @code{\lyricsto}.  In this mode you can enter lyrics,
 with punctuation and accents, and the input @code{d} is not parsed as
 a pitch, but rather as a one letter syllable.  Syllables are entered
 like notes, but with pitches replaced by text.  For example,
+
 @example
 \lyricmode @{ Twin-4 kle4 twin- kle litt- le star2 @}
 @end example
 
-There is a difference between @code{\addlyrics} and
-@code{\lyricmode}.  @code{\addlyrics} and @code{\lyricsto}
-ignore all durations and aligns syllables to notes; @code{\lyricmode}
-uses the durations specified.
+There are two main methods to specify the horizontal placement
+of the syllables, either by specifying the duration of each syllable
+explicitly, like in the example above, or by automatically aligning
+the lyrics to a melody or other voice of music, using @code{\addlyrics}
+or @code{\lyricsto}.
+@c  TODO: broken
+@c For more details see @ref{The Lyrics context}.
 
-A word lyrics mode begins with an alphabetic character, and ends with
+A word or syllable of lyrics begins with an alphabetic character, and ends
+with
 any space or digit.  The following characters can be any character
-that is not a digit or white space.  One important consequence of this
-is that a word can end with @code{@}}.  The following example is
-usually a mistake in the input file.  The syllable includes a @code{@}}, so the
-opening brace is not balanced
+that is not a digit or white space.
+
+Any character that is not a digit or white space will be regarded as
+part of the syllable; one important consequence of this is that a word
+can end with @code{@}}, which often leads to the following mistake:
+
 @example
-\lyricmode @{ twinkle@}
+\lyricmode @{ lah- lah@}
 @end example
 
-@cindex @code{\property}, in @code{\lyricmode}
+In this example, the @code{@}} is included in the final syllable, so the
+opening brace is not balanced and the input file will probably not
+compile.
+
+
+@funindex \property in \lyricmode
+
 @noindent
 Similarly, a period which follows an alphabetic sequence is included in
 the resulting string.  As a consequence, spaces must be inserted around
-property commands
+property commands: do @emph{not} write
+
+@example
+\override Score.LyricText #'font-shape = #'italic
+@end example
+
+@noindent
+but instead use
+
 @example
 \override Score . LyricText #'font-shape = #'italic
 @end example
 
-@cindex @code{_}
+@funindex _
 @cindex spaces, in lyrics
 @cindex quotes, in lyrics
+@cindex ties, in lyrics
+
+In order to assign more than one syllable to a single note, you can
+surround them with quotes or use a @code{_} character, to get spaces
+between syllables, or use tilde  symbol (@code{~}) to get a lyric tie.
+
+@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
+\time 3/4
+\relative { c2 e4 g2 e4 }
+\addlyrics { gran- de_a- mi- go }
+\addlyrics { pu- "ro y ho-" nes- to }
+\addlyrics { pu- ro~y~ho- nes- to }
+@end lilypond
+
+The lyric tie is implemented with the Unicode character U+203F, so be
+sure to have a font (Like DejaVuLGC) installed that includes this
+glyph.
 
-Any @code{_} character that appears in an unquoted word is converted
-to a space.  This provides a mechanism for introducing spaces into words
-without using quotes.
 
 To enter lyrics with characters from non-English languages, or with
-non-ascii characters (such as the heart symbol or slanted quotes),
+accented and special characters (such as the heart symbol or slanted quotes),
 simply insert the characters directly into the input file and save
-it with utf-8 encoding.  See @ref{Text encoding} for more info.
+it with utf-8 encoding.  See @ref{Text encoding}, for more info.
 
-@example
-\lyricmode @{ He said: “Let my peo ple go”. @}
-@end example
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative { e4 f e d e f e2 }
+\addlyrics { He said: “Let my peo ple go”. }
+@end lilypond
+
+To use normal quotes in lyrics, add a backslash before the
+quotes.  For example,
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\relative c' { \time 3/4 e4 e4. e8 d4 e d c2. }
+\addlyrics { "\"I" am so lone- "ly\"" said she }
+@end lilypond
 
 The full definition of a word start in Lyrics mode is somewhat more
 complex.
@@ -833,142 +867,234 @@ any 8-bit character with ASCII code over 127, or a two-character
 combination of a backslash followed by one of @code{`}, @code{'},
 @code{"}, or @code{^}.
 
+To define identifiers containing lyrics, the function @code{lyricmode}
+must be used.
 
+@example
+verseOne = \lyricmode @{ Joy to the world the Lord is come @}
+\score @{
+  <<
+    \new Voice = "one" \relative c'' @{
+      \autoBeamOff
+      \time 2/4
+      c4 b8. a16 g4. f8 e4 d c2
+    @}
+    \addlyrics @{ \verseOne @}
+  >>
+@}
+@end example
 
-@seealso
-
-Program reference: @internalsref{LyricText}.
 
-@refbugs
+@seealso
 
-The definition of lyrics mode is too complex.
+Program reference: @internalsref{LyricText}, @internalsref{LyricSpace}.
 
-@node Hyphens and extenders
-@subsection Hyphens and extenders
 
-@cindex hyphens
 
-Centered hyphens are entered as `@code{--}' between syllables.
-The hyphen will have variable length depending on the space between
-the syllables and it will be centered between the syllables.
+@node Aligning lyrics to a melody
+@subsection Aligning lyrics to a melody
 
-@cindex melisma
-@cindex extender
+@funindex \lyricmode
+@funindex \addlyrics
+@funindex \lyricsto
 
-When a lyric is sung over many notes (this is called a melisma), this is
-indicated with a horizontal line centered between a syllable and the
-next one.  Such a line is called an extender line, and it is entered as
-`@code{__}'.
 
-In tighly engraved music, hyphens can be removed.  In some languages
-(e.g. German and Hungarian), hyphens should not disappear, since
-spelling depends on hyphenation.  For that purpose, hyphens can be
-forced to remain by overriding @code{minimum-length} of
-the @code{LyricHyphen} grob.
+Lyrics are printed by interpreting them in the context called
+@internalsref{Lyrics}.
 
-@lilypond[quote,verbatim,raggedright]
-\score {
- <<
-  \new Staff \relative c'' {
-    \time 1/4 c16 c c c c16 c c c c16 c c c
-  }
-  \lyricmode { \new Lyrics
-    \with {
-      \override SeparationItem #'padding = #0.0
-      % Otherwise lyrics are so far apart that hyphens don't disappear
-    } 
-    {
-      An -- ti -- cons -- ti --
-      tu -- tion -- nel -- le --
-      \override LyricHyphen  #'minimum-length = #0.7
-      \override LyricHyphen  #'callbacks #'springs-and-rods =
-        #Hyphen_spanner::set_spacing_rods
-      men -- taire -- ment. ouf~!
-    }
-  }
- >>
- \layout   {
-  indent = 0.0 \cm
-  linewidth = 3.4 \cm
-  \context {
-    \Staff \remove "Time_signature_engraver"
-  }
- }
-}
-@end lilypond
-
-@seealso
-
-Program reference: @internalsref{LyricHyphen}, @internalsref{LyricExtender}.
+@example
+\new Lyrics \lyricmode @dots{}
+@end example
 
+There are two main methods to specify the horizontal placement
+of the syllables:
 
+@itemize @bullet
+@item
+by automatically aligning
+the lyrics to a melody or other voice of music, using @code{\addlyrics}
+or @code{\lyricsto}.
 
-@node The Lyrics context
-@subsection The Lyrics context
+@item
+or by specifying the duration of each syllable
+explicitly, using @code{\lyricmode}
+@end itemize
 
+@menu
+* Automatic syllable durations::  
+* Another way of entering lyrics::  
+* Assigning more than one syllable to a single note::  
+* More than one note on a single syllable::  
+* Extenders and hyphens::       
+@end menu
 
-Lyrics are printed by interpreting them in a @internalsref{Lyrics} context
-@example
-\context Lyrics \lyricmode @dots{}
-@end example
+@node Automatic syllable durations
+@subsubsection Automatic syllable durations
 
 @cindex automatic syllable durations
-@cindex @code{\lyricsto}
 @cindex lyrics and melodies
 
-This will place the lyrics according to the durations that were
-entered.  The lyrics can also be aligned under a given melody
-automatically.  In this case, it is no longer necessary to enter the
-correct duration for each syllable.  This is achieved by combining the
+The lyrics can be aligned under a given melody
+automatically.  This is achieved by combining the
 melody and the lyrics with the @code{\lyricsto} expression
+
 @example
-\lyricsto @var{name} \new Lyrics @dots{}
+\new Lyrics \lyricsto @var{name} @dots{}
 @end example
 
 This aligns the lyrics to the
-notes of the @internalsref{Voice} context called @var{name}, which has
-to exist.  Therefore, normally the @code{Voice} is specified first, and
+notes of the @internalsref{Voice} context called @var{name}, which must
+already exist.  Therefore normally the @code{Voice} is specified first, and
 then the lyrics are specified with @code{\lyricsto}.  The command
 @code{\lyricsto} switches to @code{\lyricmode} mode automatically, so the
 @code{\lyricmode} keyword may be omitted.
 
-For different or more complex orderings, the best way is to setup the
-hierarchy of staves and lyrics first, e.g.,
-@example
-\context ChoirStaff <<
-  \context Lyrics = sopranoLyrics @{ s1 @}
-  \context Voice = soprano @{ @emph{music} @}
-  \context Lyrics = tenorLyrics @{ s1 @}
-  \context Voice = tenor @{ @emph{music} @}
+The following example uses different commands for entering lyrics.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+<<
+  \new Voice = "one" \relative c'' {
+    \autoBeamOff
+    \time 2/4
+    c4 b8. a16 g4. f8 e4 d c2
+  }
+  \new Lyrics \lyricmode { Joy4 to8. the16 world!4. the8 Lord4 is come.2 }
+  \new Lyrics \lyricmode { Joy to the earth! the Sa -- viour reigns. }
+  \new Lyrics \lyricsto "one" { No more let sins and sor -- rows grow. }
 >>
-@end example
-and then combine the appropriate melodies and lyric lines
+@end lilypond
+
+The second stanza is not properly aligned because the durations
+were not specified.  A solution for that would be to use @code{\lyricsto}.
+
+The @code{\addlyrics} command is actually just a convenient way
+to write a more complicated LilyPond structure that sets up the
+lyrics.
+
 @example
-\lyricsto "soprano" \context Lyrics = sopranoLyrics
-  @emph{the lyrics}
+@{ MUSIC @}
+\addlyrics @{ LYRICS @}
 @end example
 
 @noindent
-The final input would resemble
+is the same as
 
 @example
-<<\context ChoirStaff << @emph{setup the music} >>
-  \lyricsto "soprano" @emph{etc}
-  \lyricsto "alto" @emph{etc}
-  @emph{etc}
->>
+\new Voice = "blah" @{ music @}
+\new Lyrics \lyricsto "blah" @{ LYRICS @}
 @end example
 
+@node Another way of entering lyrics
+@subsubsection Another way of entering lyrics
 
-The @code{\lyricsto} command detects melismata: it only puts one
+Lyrics can also be entered without @code{\addlyrics} or
+@code{\lyricsto}.  In this case,
+syllables are entered like notes -- but with pitches replaced by text -- and the
+duration of each syllable must be entered explicitly. For example:
+ 
+@example
+play2 the4 game2.
+sink2 or4 swim2.
+@end example
+ 
+The alignment to a melody can be specified with the
+@code{associatedVoice} property,
+ 
+@example
+\set associatedVoice = #"lala"
+@end example
+ 
+@noindent
+The value of the property (here: @code{"lala"}) should be the name of
+a @internalsref{Voice} context.  Without this setting, extender lines
+will not be formatted properly.
+ 
+Here is an example demonstrating manual lyric durations,
+ 
+@lilypond[relative=1,ragged-right,verbatim,fragment,quote]
+<< \new Voice = "melody" {
+    \time 3/4
+    c2 e4 g2.
+ }
+ \new Lyrics \lyricmode {
+   \set associatedVoice = #"melody"
+   play2 the4 game2.
+ } >>
+@end lilypond
+
+@seealso
+ 
+Program reference: @internalsref{Lyrics}.
+
+
+@node Assigning more than one syllable to a single note
+@subsubsection Assigning more than one syllable to a single note
+
+
+@funindex _
+@cindex ties, in lyrics
+
+In order to assign more than one syllable to a single note, you can
+surround them with quotes or use a @code{_} character, to get spaces
+between syllables, or use tilde  symbol (@code{~}) to get a lyric
+tie@footnote{The lyric ties is implemented with the Unicode character
+U+203F, so be
+sure to have a font (Like DejaVuLGC) installed that includes this
+glyph.}.
+
+@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
+\time 3/4
+\relative { c2 e4 g2 e4 }
+\addlyrics { gran- de_a- mi- go }
+\addlyrics { pu- "ro y ho-" nes- to }
+\addlyrics { pu- ro~y~ho- nes- to }
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{LyricCombineMusic}.
+
+@c Here come the section which used to be "Melismata"
+@c the new title might be more self-explanatory
+
+
+@node More than one note on a single syllable
+@subsubsection More than one note on a single syllable
+
+@cindex melisma
+@cindex melismata
+@cindex phrasing, in lyrics
+
+Sometimes, particularly in Medieval music, several notes are to be sung on one
+single syllable; such vocalises are called melismas, or melismata.
+
+@c this method seems to be the simplest; therefore
+@c it might be better to present it first - vv
+
+You can define melismata entirely in the lyrics, by entering @code{_}
+for every note
+that is part of the melisma.
+
+@lilypond[relative=1,verbatim,fragment,quote]
+{ \set melismaBusyProperties = #'()
+ c d( e) f f( e) e e  }
+\addlyrics
+ { Ky -- _ _ ri __ _ _ _  e }
+@end lilypond
+
+In this case, you can also have ties and slurs in the melody if you
+set @code{melismaBusyProperties}, as is done in the example above.
+
+However, the @code{\lyricsto} command can also
+detect melismata automatically: it only puts one
 syllable under a tied or slurred group of notes.  If you want to force
 an unslurred group of notes to be a melisma, insert @code{\melisma}
 after the first note of the group, and @code{\melismaEnd} after the
 last one, e.g.,
 
-@lilypond[quote,relative=2,raggedright,fragment,verbatim]
+@lilypond[quote,relative=2,ragged-right,fragment,verbatim]
 <<
-  \context Voice = "lala" {
+  \new Voice = "lala" {
     \time 3/4
     f4 g8
     \melisma
@@ -976,7 +1102,7 @@ last one, e.g.,
     \melismaEnd
     e2
   }
-  \lyricsto "lala" \new Lyrics {
+  \new Lyrics \lyricsto "lala" {
     la di __ daah
   }
 >>
@@ -986,49 +1112,8 @@ In addition, notes are considered a melisma if they are manually
 beamed, and automatic beaming (see @ref{Setting automatic beam
 behavior}) is switched off.
 
-@ignore
-
-@c nonformation:
-
-The criteria for deciding melismata can
-be tuned with the property @code{melismaBusyProperties}.  See
-@internalsref{Melisma_translator} in the program reference for more
-information.
-
-@end ignore
-
-Lyrics can also be entered without @code{\lyricsto}.  In this case the
-duration of each syllable must be entered explicitly, for example,
-
-@example
-play2 the4 game2.
-sink2 or4 swim2.
-@end example
-
-The alignment to a melody can be specified with the
-@code{associatedVoice} property,
-
-@example
-\set associatedVoice = #"lala"
-@end example
-
-@noindent
-The value of the property (here: @code{"lala"}) should be the name of
-a @internalsref{Voice} context.  Without this setting, extender lines
-will not be formatted properly.
-
-Here is an example demonstrating manual lyric durations,
-
-@lilypond[relative=1,raggedright,verbatim,fragment,quote]
-<< \context Voice = melody {
-     \time 3/4
-     c2 e4 g2.
-  }
-  \new Lyrics \lyricmode {
-    \set associatedVoice = #"melody"
-    play2 the4 game2.
-  } >>
-@end lilypond
+@c TODO: there might be some more relevant place for 
+@c the following link (?)
 
 @cindex SATB
 @cindex choral score
@@ -1040,48 +1125,141 @@ A complete example of a SATB score setup is in section
 @refcommands
 
 @code{\melisma}, @code{\melismaEnd}
-@cindex @code{\melismaEnd}
-@cindex @code{\melisma}
+@funindex \melismaEnd
+@funindex \melisma
 
 @seealso
 
-Program reference: @internalsref{LyricCombineMusic},
-@internalsref{Lyrics}, @internalsref{Melisma_translator}.
-
+Program reference: @internalsref{Melisma_translator}.
 
-@inputfileref{input/@/regression,lyric@/-combine@/-new@/.ly}.
-@c TODO: make separate section for melismata
+@lsr{vocal,lyric@/-combine.ly}.
 
 @refbugs
 
 Melismata are not detected automatically, and extender lines must be
 inserted by hand.
 
+@node Extenders and hyphens
+@subsubsection Extenders and hyphens
+
+@cindex melisma
+@cindex extender
+
+Melismata are indicated with a horizontal line centered between a syllable
+and the next one.  Such a line is called an extender line, and it is entered
+as @samp{ __ } (note the spaces before and after the two underscore
+characters).
+
+@cindex hyphens
+
+Centered hyphens are entered as @samp{ -- } between syllables of a same word
+(note the spaces before and after the two hyphen characters).  The hyphen
+will be centered between the syllables, and its length will be adjusted
+depending on the space between the syllables.
+
+In tighly engraved music, hyphens can be removed.  Whether this
+happens can be controlled with the @code{minimum-distance} (minimum
+distance between two syllables) and the @code{minimum-length}
+(threshold below which hyphens are removed).
+
+@seealso
+
+Program reference: @internalsref{LyricExtender},
+@internalsref{LyricHyphen}
+
+
+@node Working with lyrics and identifiers
+@subsection Working with lyrics and identifiers
+@cindex lyrics, identifiers
+
+To define identifiers containing lyrics, the function @code{\lyricmode}
+must be used. You do not have to enter durations though, if you add
+@code{\addlyrics} or @code{\lyricsto}
+when invoking your identifier.
+ 
+@example
+verseOne = \lyricmode @{ Joy to the world the Lord is come @}
+\score @{
+ <<
+   \new Voice = "one" \relative c'' @{
+     \autoBeamOff
+     \time 2/4
+     c4 b8. a16 g4. f8 e4 d c2
+   @}
+   \addlyrics @{ \verseOne @}
+ >>
+@}
+@end example
+ 
+For different or more complex orderings, the best way is to setup the
+hierarchy of staves and lyrics first, e.g.,
+@example
+\new ChoirStaff <<
+  \new Voice = "soprano" @{ @emph{music} @}
+  \new Lyrics = "sopranoLyrics" @{ s1 @}
+  \new Lyrics = "tenorLyrics" @{ s1 @}
+  \new Voice = "tenor" @{ @emph{music} @}
+>>
+@end example
+ 
+and then combine the appropriate melodies and lyric lines
+ 
+@example
+\context Lyrics = sopranoLyrics \lyricsto "soprano"
+@emph{the lyrics}
+@end example
+ 
+@noindent
 
+The final input would resemble
+ 
+@example
+<<\new ChoirStaff << @emph{setup the music} >>
+ \lyricsto "soprano" @emph{etc}
+ \lyricsto "alto" @emph{etc}
+@emph{etc}
+>>
+@end example
+ 
+@seealso
+ 
 @c TODO: document \new Staff << Voice \lyricsto >> bug
+Program reference: @internalsref{LyricCombineMusic},
+@internalsref{Lyrics}.  
 
-@node Flexibility in alignment
-@subsection Flexibility in alignment
+
+@node Flexibility in placement
+@subsection Flexibility in placement
 
 Often, different stanzas of one song are put to one melody in slightly
 differing ways.  Such variations can still be captured with
 @code{\lyricsto}.
 
-@subsubsection Lyrics to multiple notes of a melisma 
+@menu
+* Lyrics to multiple notes of a melisma::  
+* Divisi lyrics::               
+* Switching the melody associated with a lyrics line::  
+* Lyrics independent of notes::  
+@end menu
 
 
+@node Lyrics to multiple notes of a melisma
+@subsubsection Lyrics to multiple notes of a melisma
+
 One possibility is that the text has a melisma in one stanza, but
 multiple syllables in another one.  One solution is to make the faster
 voice ignore the melisma.  This is done by setting
 @code{ignoreMelismata} in the Lyrics context.
 
-There has one tricky aspect.  The setting for @code{ignoreMelismata}
+There is one tricky aspect: the setting for @code{ignoreMelismata}
 must be set one syllable @emph{before} the non-melismatic syllable
 in the text, as shown here,
 
-@lilypond[verbatim,raggedright,quote]
+@c  FIXME: breaks compile
+@lilypond[verbatim,ragged-right,quote]
+%{
 <<
-  \relative \context Voice = "lahlah" {
+  \relative \new Voice = "lahlah" {
     \set Staff.autoBeaming = ##f
     c4
     \slurDotted
@@ -1098,41 +1276,87 @@ in the text, as shown here,
     still
   }
 >>
+%}
+@end lilypond
+
+
+The @code{ignoreMelismata} applies to the syllable @q{fas}, so it
+should be entered before @q{go}.
+
+The reverse is also possible: making a lyric line slower than the
+standard.  This can be achieved by insert @code{\skip}s into the
+lyrics.  For every @code{\skip}, the text will be delayed another note.
+For example,
+
+@lilypond[verbatim,ragged-right,quote]
+\relative { c c g' }
+\addlyrics {
+  twin -- \skip 4
+  kle
+}
+@end lilypond
+
+
+@node Divisi lyrics
+@subsubsection Divisi lyrics
+
+You can display alternate (or divisi) lyrics by naming voice
+contexts and attaching lyrics to those specific contexts.
+
+@lilypond[verbatim,ragged-right,quote]
+\score{ <<
+  \new Voice = "melody" {
+    \relative c' {
+      c4
+      <<
+        { \voiceOne c8 e }
+        \new Voice = "splitpart" { \voiceTwo c4 }
+      >>
+      \oneVoice c4 c | c
+    }
+  }
+  \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
+  \new Lyrics \lyricsto "splitpart" { will }
+>> }
 @end lilypond
 
 
-The @code{ignoreMelismata} applies to the syllable ``fas'', so it
-should be entered before ``go''.
-
-The reverse is also possible: making a lyric line slower than the
-standard.  This can be achieved by insert @code{\skip}s into the
-lyrics.  For every @code{\skip}, the text will be delayed another note.
-For example,
+You can use this trick to display different lyrics for a repeated
+section.
 
-@lilypond[verbatim,raggedright,quote]
-\relative { c c g' }
-\addlyrics {
-  twin -- \skip 4
-  kle
+@lilypond[verbatim,ragged-right,quote]
+\score{ <<
+  \new Voice = "melody" \relative c' {
+    c2 e | g e | c1 |
+    \new Voice = "verse" \repeat volta 2 {c4 d e f | g1 | }
+    a2 b | c1}
+  \new Lyrics = "mainlyrics" \lyricsto melody \lyricmode {
+    do mi sol mi do
+    la si do }
+  \context Lyrics = "mainlyrics" \lyricsto verse \lyricmode {
+   do re mi fa sol }
+  \new Lyrics = "repeatlyrics" \lyricsto verse \lyricmode {
+   dodo rere mimi fafa solsol }
+>>
 }
 @end lilypond
 
 
-@subsection Switching the melody associated with a lyrics line
-
 
+@node Switching the melody associated with a lyrics line
+@subsubsection Switching the melody associated with a lyrics line
 
 More complex variations in text underlay are possible.  It is possible
 to switch the melody for a line of lyrics during the text.  This is
 done by setting the @code{associatedVoice} property.  In the example
 
-@lilypond[raggedright,quote]
+@lilypond[ragged-right,quote]
 <<
-  \relative \context Voice = "lahlah" {
+  \relative \new Voice = "lahlah" {
     \set Staff.autoBeaming = ##f
     c4
     <<
-      \context Voice = alternative {
+      \new Voice = "alternative" {
         \voiceOne
         \times 2/3 {
           % show associations clearly.
@@ -1163,7 +1387,7 @@ done by setting the @code{associatedVoice} property.  In the example
 @end lilypond
 
 @noindent
-the text for the first stanza is set to a melody called ``lahlah'',
+the text for the first stanza is set to a melody called @q{lahlah},
 
 @example
 \new Lyrics \lyricsto "lahlah" @{
@@ -1173,7 +1397,7 @@ the text for the first stanza is set to a melody called ``lahlah'',
 
 
 The second stanza initially is set to the @code{lahlah} context, but
-for the syllable ``ran'', it switches to a different melody.
+for the syllable @q{ran}, it switches to a different melody.
 This is achieved with
 @example
 \set associatedVoice = alternative
@@ -1183,7 +1407,7 @@ This is achieved with
 Here, @code{alternative} is the name of the @code{Voice} context
 containing the triplet.
 
-Again, the command must be one syllable too early, before ``Ty'' in
+Again, the command must be one syllable too early, before @q{Ty} in
 this case.
 
 @example
@@ -1202,44 +1426,48 @@ The underlay is switched back to the starting situation by assigning
 @code{lahlah} to @code{associatedVoice}.
 
 
+@node Lyrics independent of notes
+@subsubsection Lyrics independent of notes
 
-@subsection Specifying melismata within the lyrics
-
-It is also possible to define melismata entirely in the lyrics. This
-can be done by entering @code{_} for every note that is part of the
-melisma. 
+In some complex vocal music, it may be desirable to place
+lyrics completely independently of notes.  Music defined
+inside @code{lyricrhythm} disappears into the
+@code{Devnull} context, but the rhythms can still be used
+to place the lyrics.
 
-@lilypond[relative=1,verbatim,fragment] 
-{ \set melismaBusyProperties = #'()
-  c d( e) f f( e) e e  }
-\addlyrics
- { Ky -- _ _ ri __ _ _ _  e }
-@end lilypond
+@lilypond[quote,verbatim,ragged-right]
+voice = {
+  c''2
+  \tag #'music { c''2 }
+  \tag #'lyricrhythm { c''4. c''8 }
+  d''1
+}
 
-In this case, you can also have ties and slurs in the melody, if you
-set @code{melismaBusyProperties}, as is done in the example above.
+lyr = \lyricmode { I like my cat! }
 
-@lilypond[relative=1,verbatim,fragment]
-{
- \set melismaBusyProperties = #'()
-  c d( e) f f( e) e e
-}
-\addlyrics
- { Ky -- _ _ ri __ _ _ _  e }
+<<
+  \new Staff \keepWithTag #'music \voice
+  \new Devnull="nowhere" \keepWithTag #'lyricrhythm \voice
+  \new Lyrics \lyricsto "nowhere" \lyr
+  \new Staff { c'8 c' c' c' c' c' c' c'
+  c' c' c' c' c' c' c' c' }
+>>
 @end lilypond
 
-@subsubsection Spacing lyrics
+
+@node Spacing lyrics
+@subsection Spacing lyrics
 
 @cindex Spacing lyrics
 @cindex Lyrics, increasing space between
 
-To increase the space between lyrics, use the @code{SeparationItem}
-property.
+To increase the spacing between lyrics, set the minimum-distance property of
+LyricSpace.
 
-@lilypond[relative,verbatim,fragment,quote,raggedright]
-{ 
+@lilypond[relative,verbatim,fragment,quote,ragged-right]
+{
   c c c c
-  \override Score.SeparationItem #'padding = #5
+  \override Lyrics.LyricSpace #'minimum-distance = #1.0
   c c c c
 }
 \addlyrics {
@@ -1248,21 +1476,38 @@ property.
 }
 @end lilypond
 
+To make this change for all lyrics in the score, set the property in the
+layout.
 
+@lilypond[relative,verbatim,quote,ragged-right]
+\score {
+  \relative c' {
+  c c c c
+  c c c c
+  }
+  \addlyrics {
+  longtext longtext longtext longtext
+  longtext longtext longtext longtext
+  }
+  \layout {
+    \context {
+      \Lyrics
+      \override LyricSpace #'minimum-distance = #1.0
+    }
+  }
+}
+@end lilypond
 
-@node More stanzas
-@subsection More stanzas
-
-@cindex phrasing, in lyrics
 
+@node More about stanzas
+@subsection More about stanzas
 
 @cindex stanza number
-@cindex singer's names
-@cindex name of singer
+@subsubsection Adding stanza numbers 
 
 Stanza numbers can be added by setting @code{stanza}, e.g.,
 
-@lilypond[quote,raggedright,verbatim,relative=2,fragment]
+@lilypond[quote,ragged-right,verbatim,relative=2,fragment]
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {
@@ -1270,18 +1515,48 @@ Stanza numbers can be added by setting @code{stanza}, e.g.,
   Hi, my name is Bert.
 } \addlyrics {
   \set stanza = "2. "
-  Oh, che -- ri, je t'aime
+  Oh, ché -- ri, je t'aime
+}
+@end lilypond
+
+@noindent
+These numbers are put just before the start of the first syllable.
+
+
+@subsubsection Adding dynamics marks
+
+Stanzas differing in loudness may be indicated by putting a
+dynamics mark before each stanza.  In Lilypond, everthing coming in
+front of a stanza goes into the @code{StanzaNumber} object; dynamics marks
+are no different.  For technical reasons, you have to set the stanza
+outside @code{\lyricmode}:
+
+@lilypond[quote,ragged-right,verbatim]
+text = {
+  \set stanza = \markup { \dynamic "ff" "1. " }
+  \lyricmode {
+    Big bang
+  }
 }
+
+<<
+  \new Voice = "tune" {
+    \time 3/4
+    g'4 c'2
+  }
+\new Lyrics \lyricsto "tune" \text
+>>
 @end lilypond
 
-These numbers are put just before the start of first syllable.
+@cindex singer name
+@cindex name of singer
+@subsubsection Adding singer names
 
 Names of singers can also be added.  They are printed at the start of
 the line, just like instrument names.  They are created by setting
-@code{vocalName}.  A short version may be entered as @code{vocNam}.
+@code{vocalName}.  A short version may be entered as @code{shortVocalName}.
 
-
-@lilypond[fragment,raggedright,quote,verbatim,relative=2]
+@lilypond[fragment,ragged-right,quote,verbatim,relative=2]
 \new Voice {
   \time 3/4 g2 e4 a2 f4 g2.
 } \addlyrics {
@@ -1293,51 +1568,123 @@ the line, just like instrument names.  They are created by setting
 }
 @end lilypond
 
-You can display alternate (or divisi) lyrics by naming voice
-contexts and attaching lyrics to those specific contexts.
 
-@lilypond[verbatim,raggedright,quote]
+@subsubsection Printing stanzas at the end 
+
+Sometimes it is appropriate to have one stanza set
+to the music, and the rest added in verse form at
+the end of the piece.  This can be accomplished by adding
+the extra verses into a @code{\markup} section outside
+of the main score block.  Notice that there are two
+different ways to force linebreaks when using
+@code{\markup}.
+
+@lilypond[ragged-right,verbatim,quote]
+melody = \relative c' {
+e d c d | e e e e |
+d d e d | c1 |
+}
+
+text = \lyricmode {
+\set stanza = "1." Ma- ry had a lit- tle lamb,
+its fleece was white as snow.
+}
+
 \score{ <<
-  \context Voice = "melody" {
-    \relative c' {
-      c4
-      <<
-        { \voiceOne c8 e }
-        \context Voice = splitpart { \voiceTwo c4 }
-      >>
-      \oneVoice c4 c | c
-    }
+  \new Voice = "one" { \melody }
+  \new Lyrics \lyricsto "one" \text
+>>
+  \layout { }
+}
+\markup { \column{
+  \line{ Verse 2. }
+  \line{ All the children laughed and played }
+  \line{ To see a lamb at school. }
   }
-  \new Lyrics \lyricsto "melody" { we shall not o- ver- come }
-  \new Lyrics \lyricsto "splitpart" { will }
->> }
+}
+\markup{
+  \wordwrap-string #"
+  Verse 3.
+
+  Mary took it home again,
+
+  It was against the rule."
+}
 @end lilypond
 
 
-You can use this trick to display different lyrics for a repeated
-section.
+@subsubsection Printing stanzas at the end in multiple columns 
+
+When a piece of music has many verses, they are often printed in
+multiple columns across the page. An outdented verse number often
+introduces each verse. The following example shows how to produce such
+output in Lilypond.
+
+@lilypond[ragged-right,quote,verbatim]
+melody = \relative c' {
+  c c c c | d d d d
+}
+ 
+text = \lyricmode {
+  \set stanza = "1." This is verse one.
+  It has two lines.
+}
 
-@lilypond[verbatim,raggedright,quote]
 \score{ <<
-  \context Voice = melody \relative c' {
-    c2 e | g e | c1 |
-    \context Voice = verse \repeat volta 2 {c4 d e f | g1 | }
-    a2 b | c1}
-  \lyricsto melody  \context Lyrics = mainlyrics \lyricmode {
-    do mi sol mi do
-    la si do }
-  \lyricsto verse \context Lyrics = mainlyrics \lyricmode {
-   do re mi fa sol }
-  \lyricsto verse \context Lyrics = repeatlyrics \lyricmode {
-   dodo rere mimi fafa solsol }
->>
+    \new Voice = "one" { \melody }
+    \new Lyrics \lyricsto "one" \text
+   >>
+  \layout { }
+}
+
+\markup {
+  \fill-line {
+    \hspace #0.1 % moves the column off the left margin; can be removed if
+        % space on the page is tight
+     \column {
+      \line { \bold "2."
+        \column {
+          "This is verse two."
+          "It has two lines."
+        }
+      }
+      \hspace #0.1 % adds vertical spacing between verses
+      \line { \bold "3."
+        \column {
+          "This is verse three."
+          "It has two lines."
+        }
+      }
+    }
+    \hspace #0.1  % adds horizontal spacing between columns; if they are
+        % still too close, add more " " pairs until the result 
+        % looks good
+     \column {
+      \line { \bold "4."
+        \column {
+          "This is verse four."
+          "It has two lines."
+        }
+      }
+      \hspace #0.1 % adds vertical spacing between verses
+      \line { \bold "5."
+        \column {
+          "This is verse five."
+          "It has two lines."
+        }
+      }
+    }
+  \hspace #0.1 % gives some extra space on the right margin; can
+      % be removed if page space is tight
+  }
 }
 @end lilypond
 
 
 @seealso
 
-Program reference: @internalsref{LyricText}, @internalsref{StanzaNumber}, @internalsref{VocalName}.
+Program reference: @internalsref{LyricText}, @internalsref{StanzaNumber},
+@internalsref{VocalName}.
 
 
 
@@ -1367,7 +1714,7 @@ for example,
 
 This results in the following output
 
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
 \layout {
   \context {
     \Staff
@@ -1385,7 +1732,7 @@ ambitus per staff rather than per each voice, add the
 @internalsref{Ambitus_engraver} to the @internalsref{Staff} context
 rather than to the @internalsref{Voice} context.  Here is an example,
 
-@lilypond[verbatim,raggedright,quote]
+@lilypond[verbatim,ragged-right,quote]
 \new Staff \with {
   \consists "Ambitus_engraver"
 }
@@ -1393,8 +1740,7 @@ rather than to the @internalsref{Voice} context.  Here is an example,
   \new Voice \with {
     \remove "Ambitus_engraver"
   } \relative c'' {
-    \override Ambitus #'X-offset-callbacks
-      = #(list (lambda (grob axis) -1.0))
+    \override Ambitus #'X-offset = #-1.0
     \voiceOne
     c4 a d e f2
   }
@@ -1411,8 +1757,7 @@ rather than to the @internalsref{Voice} context.  Here is an example,
 This example uses one advanced feature,
 
 @example
-\override Ambitus #'X-offset-callbacks
-  = #(list (lambda (grob axis) -1.0))
+\override Ambitus #'X-offset = #-1.0
 @end example
 
 @noindent
@@ -1426,7 +1771,8 @@ Program reference: @internalsref{Ambitus},
 @internalsref{AmbitusLine}, @internalsref{AmbitusNoteHead},
 @internalsref{AmbitusAccidental}.
 
-Examples: @inputfileref{input/@/regression,ambitus@/.ly}.
+Examples:
+@lsr{vocal,ambitus@/.ly}.
 
 @refbugs
 
@@ -1447,11 +1793,14 @@ can ask them for specific instructions about where to move these
 examples, and that might get them more involved in the docs.  -gp
 @end ignore
 
-``Parlato'' is spoken without pitch but still with rhythm; it is
+@q{Parlato} is spoken without pitch but still with rhythm; it is
 notated by cross noteheads.  This is demonstrated in
 @ref{Special noteheads}.
 
 
+
+
+
 @node Rhythmic music
 @section Rhythmic music
 
@@ -1462,6 +1811,7 @@ also be used to show the rhythms of melodies.
 * Showing melody rhythms::      
 * Entering percussion::         
 * Percussion staves::           
+* Ghost notes::                 
 @end menu
 
 
@@ -1472,8 +1822,8 @@ Sometimes you might want to show only the rhythm of a melody.  This
 can be done with the rhythmic staff.  All pitches of notes on such a
 staff are squashed, and the staff itself has a single line
 
-@lilypond[quote,raggedright,fragment,relative=1,verbatim]
-\context RhythmicStaff {
+@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+\new RhythmicStaff {
   \time 4/4
   c4 e8 f g2 | r4 g r2 | g1:32 | r1 |
 }
@@ -1483,8 +1833,6 @@ staff are squashed, and the staff itself has a single line
 
 Program reference: @internalsref{RhythmicStaff}.
 
-Examples: @inputfileref{input/@/regression,rhythmic@/-staff@/.ly}.
-
 
 @node Entering percussion
 @subsection Entering percussion
@@ -1498,7 +1846,7 @@ similar to the standard mode for entering notes.  Each piece of
 percussion has a full name and an abbreviated name, and both can be used
 in input files
 
-@lilypond[quote,raggedright,verbatim]
+@lilypond[quote,ragged-right,verbatim]
 \drums {
   hihat hh bassdrum bd
 }
@@ -1525,7 +1873,7 @@ of percussion.
 To typeset the music, the notes must be interpreted in a
 @internalsref{DrumStaff} and @internalsref{DrumVoice} contexts
 
-@lilypond[quote,raggedright,verbatim]
+@lilypond[quote,ragged-right,verbatim]
 up = \drummode { crashcymbal4 hihat8 halfopenhihat hh hh hh openhihat }
 down = \drummode { bassdrum4 snare8 bd r bd sn4 }
   \new DrumStaff <<
@@ -1535,13 +1883,13 @@ down = \drummode { bassdrum4 snare8 bd r bd sn4 }
 @end lilypond
 
 The above example shows verbose polyphonic notation.  The short
-polyphonic notation, described in @ref{Polyphony}, can also be used if
+polyphonic notation, described in @ref{Basic polyphony}, can also be used if
 the @internalsref{DrumVoice}s are instantiated by hand first.  For example,
 
-@lilypond[quote,raggedright,fragment,verbatim]
+@lilypond[quote,ragged-right,fragment,verbatim]
 \new DrumStaff <<
-  \context DrumVoice = "1" { s1 *2 }
-  \context DrumVoice = "2" { s1 *2 }
+  \new DrumVoice = "1" { s1 *2 }
+  \new DrumVoice = "2" { s1 *2 }
   \drummode {
     bd4 sn4 bd4 sn4
     <<
@@ -1562,7 +1910,7 @@ The following variables have been predefined
 @item drums-style
 This is the default.  It typesets a typical drum kit on a five-line staff
 
-@lilypond[quote,linewidth=10.0\cm]
+@lilypond[quote,line-width=10.0\cm]
 nam = \lyricmode {
   cymc cyms cymr hh hhc hho hhho hhp
   cb hc bd sn ss tomh tommh tomml toml tomfh tomfl }
@@ -1575,9 +1923,9 @@ mus = \drummode {
        \remove Time_signature_engraver
        \override Stem #'transparent = ##t
        \override Stem #'Y-extent-callback = ##f
-       minimumVerticalExtent = #'(-4.0 . 5.0)
+       \override VerticalAxisGroup #'minimum-Y-extent = #'(-4.0 . 5.0)
      } \mus
-     \context Lyrics \nam
+     \new Lyrics \nam
   >>
   \layout {
     \context {
@@ -1597,22 +1945,22 @@ on the three middle lines you use @code{tommh}, @code{tomml}, and
 @item timbales-style
 This typesets timbales on a two line staff
 
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
 nam = \lyricmode { timh ssh timl ssl cb }
 mus = \drummode { timh ssh timl ssl cb s16 }
 
 <<
-  \context DrumStaff \with {
+  \new DrumStaff \with {
     \remove Bar_engraver
     \remove Time_signature_engraver
     \override Stem #'transparent = ##t
     \override Stem #'Y-extent-callback = ##f
     \override StaffSymbol #'line-count = #2
     \override StaffSymbol #'staff-space = #2
-    minimumVerticalExtent = #'(-3.0 . 4.0)
+    \override VerticalAxisGroup #'minimum-Y-extent = #'(-3.0 . 4.0)
     drumStyleTable = #timbales-style
   } \mus
-  \context Lyrics {
+  \new Lyrics {
     \override LyricText #'font-family = #'typewriter
     \nam
   }
@@ -1622,12 +1970,12 @@ mus = \drummode { timh ssh timl ssl cb s16 }
 @item congas-style
 This typesets congas on a two line staff
 
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
 nam = \lyricmode { cgh cgho cghm ssh cgl cglo cglm ssl }
 mus = \drummode { cgh cgho cghm ssh cgl cglo cglm ssl s16 }
 
 <<
-  \context DrumStaff \with {
+  \new DrumStaff \with {
     \remove Bar_engraver
     \remove Time_signature_engraver
     drumStyleTable = #congas-style
@@ -1638,7 +1986,7 @@ mus = \drummode { cgh cgho cghm ssh cgl cglo cglm ssl s16 }
     \override Stem #'transparent = ##t
     \override Stem #'Y-extent-callback = ##f
   } \mus
-  \context Lyrics {
+  \new Lyrics {
     \override LyricText #'font-family = #'typewriter
     \nam
   }
@@ -1648,12 +1996,12 @@ mus = \drummode { cgh cgho cghm ssh cgl cglo cglm ssl s16 }
 @item bongos-style
 This typesets bongos on a two line staff
 
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
 nam = \lyricmode { boh boho bohm ssh bol bolo bolm ssl }
 mus = \drummode { boh boho bohm ssh bol bolo bolm ssl s16 }
 
 <<
-  \context DrumStaff\with {
+  \new DrumStaff \with {
     \remove Bar_engraver
     \remove Time_signature_engraver
     \override StaffSymbol #'line-count = #2
@@ -1664,7 +2012,7 @@ mus = \drummode { boh boho bohm ssh bol bolo bolm ssl s16 }
     \override Stem #'transparent = ##t
     \override Stem #'Y-extent-callback = ##f
   } \mus
-  \context Lyrics {
+  \new Lyrics {
     \override LyricText #'font-family = #'typewriter
     \nam
   }
@@ -1674,12 +2022,12 @@ mus = \drummode { boh boho bohm ssh bol bolo bolm ssl s16 }
 @item percussion-style
 To typeset all kinds of simple percussion on one line staves.
 
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
 nam = \lyricmode { tri trio trim gui guis guil cb cl tamb cab mar hc }
 mus = \drummode { tri trio trim gui guis guil cb cl tamb cab mar hc s16 }
 
 <<
-  \context DrumStaff\with{
+  \new DrumStaff \with{
     \remove Bar_engraver
     drumStyleTable = #percussion-style
     \override StaffSymbol #'line-count = #1
@@ -1687,7 +2035,7 @@ mus = \drummode { tri trio trim gui guis guil cb cl tamb cab mar hc s16 }
     \override Stem #'transparent = ##t
     \override Stem #'Y-extent-callback = ##f
   } \mus
-  \context Lyrics {
+  \new Lyrics {
     \override LyricText #'font-family = #'typewriter
     \nam
   }
@@ -1698,7 +2046,7 @@ mus = \drummode { tri trio trim gui guis guil cb cl tamb cab mar hc s16 }
 If you do not like any of the predefined lists you can define your own
 list at the top of your file
 
-@lilypond[quote,raggedright,verbatim]
+@lilypond[quote,ragged-right,verbatim]
 #(define mydrums '(
          (bassdrum     default   #f         -1)
          (snare        default   #f         0)
@@ -1728,6 +2076,42 @@ Because general MIDI does not contain rim shots, the sidestick is used
 for this purpose instead.
 
 
+@c FIXME: check name -gp
+@node Ghost notes
+@subsection Ghost notes
+
+Ghost notes for drums and percussion may be created using the
+@code{\parenthesize} command detailed in @ref{Parentheses}.  However,
+the default @code{\drummode} does
+not include the @code{Parenthesis_engraver} plugin which allows
+this.  You
+must add the plugin explicitly in the context definition as
+detailed in @ref{Changing context properties on the fly}.
+
+@lilypond[quote,ragged-right,verbatim,fragment]
+\new DrumStaff \with {
+  \consists "Parenthesis_engraver"
+} <<
+  \context DrumVoice  = "1"  { s1 *2 }
+  \context DrumVoice  = "2" { s1 *2 }
+  \drummode {
+    <<
+      {
+        hh8[ hh] <hh sn> hh16
+        < \parenthesize sn > hh < \parenthesize
+        sn > hh8 <hh sn> hh
+      } \\ {
+        bd4 r4 bd8 bd r8 bd
+      }
+    >>
+  }
+>>
+@end lilypond
+
+@noindent
+Also note that you must add chords (@code{< >} brackets)
+around each @code{\parenthesize} statement.
+
 
 @node Guitar
 @section Guitar
@@ -1739,7 +2123,9 @@ for this purpose instead.
 * String number indications::   
 * Tablatures basic::            
 * Non-guitar tablatures::       
+* Banjo tablatures::            
 * Fret diagrams::               
+* Right hand fingerings::       
 * Other guitar issues::         
 @end menu
 
@@ -1749,18 +2135,17 @@ for this purpose instead.
 @cindex String numbers
 
 String numbers can be added to chords, by indicating the string number
-with @code{\}@var{number}, 
+with @code{\}@var{number},
 
-@lilypond[relative,relative=1,raggedright,fragment]
+@lilypond[relative,relative=1,ragged-right,fragment]
 <c\1 e\2 g\3>
 @end lilypond
 
-See also @inputfileref{input/regression,string-number.ly}.
-
 
 @seealso
 
-Program reference: @internalsref{StringNumber}.
+Program reference: @internalsref{StringNumber},
+@lsr{guitar/,string-number.ly}.
 
 
 @node Tablatures basic
@@ -1779,14 +2164,14 @@ defaults to the standard guitar tuning (with 6 strings).  The notes
 are printed as tablature, by using @internalsref{TabStaff} and
 @internalsref{TabVoice} contexts
 
-@lilypond[quote,raggedright,fragment,verbatim]
-\context TabStaff {
+@lilypond[quote,ragged-right,fragment,verbatim]
+\new TabStaff {
   a,4\5 c'\2 a\3 e'\1
   e\4 c'\2 a\3 e'\1
 }
 @end lilypond
 
-@cindex @code{minimumFret}
+@funindex minimumFret
 @cindex fret
 
 When no string is specified, the first string that does not give a
@@ -1799,19 +2184,30 @@ e16 fis gis a b4
 \set TabStaff.minimumFret = #8
 e16 fis gis a b4
 @end example
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
 frag = {
   \key e \major
   e16 fis gis a b4
   \set TabStaff.minimumFret = #8
   e16 fis gis a b4
 }
-  \context StaffGroup <<
-    \context Staff { \clef "G_8" \frag }
-    \context TabStaff { \frag }
+  \new StaffGroup <<
+    \new Staff { \clef "G_8" \frag }
+    \new TabStaff { \frag }
   >>
 @end lilypond
 
+
+@commonprop
+
+To print tablatures with stems down and horizontal beams,
+initialize the @code{TabStaff} with this code:
+
+@example
+\stemDown
+\override Beam #'damping = #100000
+@end example
+
 @seealso
 
 Program reference: @internalsref{TabStaff}, @internalsref{TabVoice}.
@@ -1822,24 +2218,40 @@ Chords are not handled in a special way, and hence the automatic
 string selector may easily select the same string to two notes in a
 chord.
 
+In order to handle @code{\partcombine}, a @code{TabStaff} must use
+specially-created voices:
+
+@lilypond[quote,ragged-right,verbatim]
+melodia = \partcombine { e4 g g g }{ e4 e e e }
+<<
+  \new TabStaff <<
+    \new TabVoice = "one" s1
+    \new TabVoice = "two" s1
+    \new TabVoice = "shared" s1
+    \new TabVoice = "solo" s1
+    { \melodia }
+  >>
+>>
+@end lilypond
+
 
 @node Non-guitar tablatures
 @subsection Non-guitar tablatures
 @cindex Non-guitar tablatures
 
-You can change the number of strings, by setting the number of lines
-in the @internalsref{TabStaff}.
-
 You can change the tuning of the strings.  A string tuning is given as
 a Scheme list with one integer number for each string, the number
 being the pitch (measured in semitones relative to middle C) of an
-open string.  The numbers specified for @code{stringTuning} are the
+open string.  The numbers specified for @code{stringTunings} are the
 numbers of semitones to subtract or add, starting the specified pitch
-by default middle C, in string order.  In the next example,
+by default middle C, in string order.  LilyPond automatically calculates
+the number of strings by looking at @code{stringTunings}.
+
+In the next example,
 @code{stringTunings} is set for the pitches e, a, d, and g
 
-@lilypond[quote,raggedright,fragment,verbatim]
-\context TabStaff <<
+@lilypond[quote,ragged-right,fragment,verbatim]
+\new TabStaff <<
   \set TabStaff.stringTunings = #'(-5 -10 -15 -20)
   {
     a,4 c' a e' e c' a e'
@@ -1847,13 +2259,67 @@ by default middle C, in string order.  In the next example,
 >>
 @end lilypond
 
+LilyPond comes with predefined string tunings for banjo, mandolin, guitar
+and bass guitar.
+
+@example
+\set TabStaff.stringTunings = #bass-tuning
+@end example
+
+The default string tuning is @code{guitar-tuning} (the standard EADGBE
+tuning).
+Some other predefined tunings are @code{guitar-open-g-tuning},
+@code{mandolin-tuning} and @code{banjo-open-g-tuning}.
+
+@seealso
+
+The file @file{scm/@/output@/-lib@/.scm} contains the predefined string
+tunings.
+Program reference: @internalsref{Tab_note_heads_engraver}.
+
 @refbugs
 
 No guitar special effects have been implemented.
 
+
+
+@node Banjo tablatures
+@subsection Banjo tablatures
+@cindex Banjo tablatures
+
+LilyPond has basic support for five stringed banjo.  When making tablatures
+for five stringed banjo, use the banjo tablature format function to get
+correct
+fret numbers for the fifth string:
+
+@lilypond[quote,ragged-right,fragment,verbatim]
+\new TabStaff <<
+  \set TabStaff.tablatureFormat = #fret-number-tablature-format-banjo
+  \set TabStaff.stringTunings = #banjo-open-g-tuning
+  {
+    \stemDown
+    g8 d' g'\5 a b g e d' |
+    g4 d''8\5 b' a'\2 g'\5 e'\2 d' |
+    g4
+  }
+>>
+@end lilypond
+
+A number of common tunings for banjo are predefined in LilyPond:
+@code{banjo-c-tuning} (gCGBD), @code{banjo-modal-tuning} (gDGCD),
+@code{banjo-open-d-tuning} (aDF#AD) and @code{banjo-open-dm-tuning}
+(aDFAD).
+
+These tunings may be converted to four string banjo tunings using the
+@code{four-string-banjo} function:
+
+@example
+\set TabStaff.stringTunings = #(four-string-banjo banjo-c-tuning)
+@end example
+
 @seealso
 
-Program reference: @internalsref{Tab_note_heads_engraver}.
+The file @file{scm/@/output@/-lib@/.scm} contains predefined banjo tunings.
 
 
 @node Fret diagrams
@@ -1865,8 +2331,8 @@ Fret diagrams can be added to music as a markup to the desired note.  The
 markup contains information about the desired fret diagram, as shown in the
 following example
 
-@lilypond[verbatim, raggedright, quote]
-\context Voice {
+@lilypond[verbatim, ragged-right, quote]
+\new Voice {
   d'^\markup \fret-diagram #"6-x;5-x;4-o;3-2;2-3;1-2;"
   d' d' d'
   fis'^\markup \override #'(size . 0.75) {
@@ -1902,7 +2368,63 @@ Details about the property interface to fret diagrams are found at
 
 @seealso
 
-Examples: @inputfileref{input/@/test,fret@/-diagram@/.ly}
+Examples: @lsrdir{guitar}
+
+
+@node Right hand fingerings
+@subsection Right hand fingerings
+
+Right hand fingerings in chords can be entered using
+@code{@var{note}-\rightHandFinger @var{finger}}
+
+@lilypond[verbatim,fragment,relative=2]
+  <c-\rightHandFinger #1 e-\rightHandFinger #2 >
+@end lilypond
+
+for brevity, you can abbreviate @code{\rightHandFinger} to something
+short, for example @code{RH},
+
+@example
+#(define RH rightHandFinger)
+@end example
+
+@cindex fingerings, right hand, for guitar 
+@cindex right hand fingerings for guitar
+ 
+@commonprop
+
+You may exercise greater control over right handing fingerings by
+setting @code{strokeFingerOrientations},
+
+@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
+#(define RH rightHandFinger)
+{
+  \set strokeFingerOrientations = #'(up down)
+  <c-\RH #1 es-\RH #2 g-\RH #4 > 4
+  \set strokeFingerOrientations = #'(up right down)
+  <c-\RH #1 es-\RH #2 g-\RH #4 > 4
+}
+@end lilypond
+
+The letters used for the fingerings are contained in the property
+@code{digit-names}, but they can also be set individually by supplying
+@code{\rightHandFinger} with a string argument, as in the following example
+
+
+@lilypond[quote,verbatim,ragged-right,fragment,relative=1]
+#(define RH rightHandFinger)
+{
+  \set strokeFingerOrientations = #'(right)
+  \override StrokeFinger #'digit-names = ##("x" "y" "z" "!" "@") 
+  <c-\RH #5 >4
+  <c-\RH "@">4  
+}
+@end lilypond
+
+@seealso
+
+Program reference: @internalsref{StrokeFinger}
+
 
 
 @node Other guitar issues
@@ -1911,20 +2433,20 @@ Examples: @inputfileref{input/@/test,fret@/-diagram@/.ly}
 This example demonstrates how to include guitar position and
 barring indications.
 
-@lilypond[quote,raggedright,fragment,verbatim,relative=0]
+@lilypond[quote,ragged-right,fragment,verbatim,relative=0]
 \clef "G_8"
 b16 d16 g16 b16 e16
 \textSpannerDown
-\override TextSpanner #'edge-text = #'("XII " . "")
+\override TextSpanner #'bound-details #'left #'text = #"XII "
   g16\startTextSpan
   b16 e16 g16 e16 b16 g16\stopTextSpan
 e16 b16 g16 d16
 @end lilypond
 
 
-Stopped (X) note heads are used in guitar music to signal a place where the 
-guitarist must play a certain note or chord, with its fingers just 
-touching the strings instead of fully pressing them.  This gives the sound a 
+Stopped (X) note heads are used in guitar music to signal a place where the
+guitarist must play a certain note or chord, with its fingers just
+touching the strings instead of fully pressing them.  This gives the sound a
 percussive noise-like sound that still maintains part of the original
 pitch.  It is notated with cross noteheads; this is
 demonstrated in @ref{Special noteheads}.
@@ -1961,24 +2483,24 @@ write @code{\taor} instead of
 @end example
 
 @code{bagpipe.ly} also contains pitch definitions for the bagpipe
-notes in the appropiate octaves, so you do not need to worry about
+notes in the appropriate octaves, so you do not need to worry about
 @code{\relative} or @code{\transpose}.
 
-@lilypond[raggedright,verbatim,quote,notime]
+@lilypond[ragged-right,verbatim,quote,notime]
 \include "bagpipe.ly"
 { \grg G4 \grg a \grg b \grg c \grg d \grg e \grg f \grA g A }
 @end lilypond
 
-Bagpipe music nominally uses the key of D Major (even though that 
-isn't really true). However, since that is the only key that can be used, 
-the key signature is normally not written out. To set this up correctly, 
-always start your music with @code{\hideKeySignature}. If you for some 
+Bagpipe music nominally uses the key of D Major (even though that
+isn't really true). However, since that is the only key that can be used,
+the key signature is normally not written out. To set this up correctly,
+always start your music with @code{\hideKeySignature}. If you for some
 reason want to show the key signature, you can use @code{\showKeySignature}
 instead.
 
 Some modern music use cross fingering on c and f to flatten those notes.
 This can be indicated by @code{cflat} or @code{fflat}. Similarly, the
-piobaireachd high g can be written @code{gflat} when it occurs in light 
+piobaireachd high g can be written @code{gflat} when it occurs in light
 music.
 
 
@@ -2004,7 +2526,7 @@ notation.
 {
   \hideKeySignature
   \time 3/4
-  \grg \partial 4 a8. d16 
+  \grg \partial 4 a8. d16
   \slurd d2 \grg f8[ e32 d16.]
   \grg f2 \grg f8 e
   \thrwd d2 \grg b4
@@ -2104,7 +2626,7 @@ up during the baroque period.
 @ref{Figured bass}
 @end itemize
 
-Here are all suptopics at a glance:
+Here are all subtopics at a glance:
 
 @menu
 * Ancient note heads::          
@@ -2128,8 +2650,7 @@ Here are all suptopics at a glance:
 @node Ancient note heads
 @subsection Ancient note heads
 
-@cindex note heads
-
+@cindex note heads, ancient
 
 For ancient notation, a note head style other than the @code{default}
 style may be chosen.  This is accomplished by setting the @code{style}
@@ -2148,7 +2669,7 @@ note heads.
 
 The following example demonstrates the @code{neomensural} style
 
-@lilypond[quote,fragment,raggedright,verbatim]
+@lilypond[quote,fragment,ragged-right,verbatim]
 \set Score.skipBars = ##t
 \override NoteHead #'style = #'neomensural
 a'\longa a'\breve a'1 a'2 a'4 a'8 a'16
@@ -2160,13 +2681,12 @@ the proper note heads, so there is no need to explicitly set the
 note head style.  Still, the note head style can be set, e.g., to
 @code{vaticana_punctum} to produce punctum neumes.  Similarly, a
 @internalsref{Mensural_ligature_engraver} is used to automatically
-assemble mensural ligatures.  See @ref{Ligatures} for how ligature
+assemble mensural ligatures.  See @ref{Ligatures}, for how ligature
 engravers work.
 
 @seealso
 
-Examples: @inputfileref{input/@/regression,note@/-head@/-style@/.ly} gives an
-overview over all available note head styles.
+@ref{Note head styles}, gives an overview over all available note head styles.
 
 
 @node Ancient accidentals
@@ -2175,11 +2695,11 @@ overview over all available note head styles.
 @cindex accidentals
 
 
-Use the @code{style} property of grob @internalsref{Accidental} to
-select ancient accidentals.   Supported styles are
-@code{mensural}, @code{vaticana}, @code{hufnagel}, and @code{medicaea}.
+Use the @code{glyph-name-alist} property of grob
+@internalsref{Accidental} and @internalsref{KeySignature} to select
+ancient accidentals. 
 
-@lilypond[quote,raggedright,staffsize=26]
+@lilypond[quote,ragged-right,staffsize=26]
 \score {
 {
   \fatText
@@ -2212,7 +2732,7 @@ select ancient accidentals.   Supported styles are
       \remove "Key_engraver"
       \remove "Time_signature_engraver"
       \remove "Staff_symbol_engraver"
-      minimumVerticalExtent = ##f
+      \override VerticalAxisGroup #'minimum-Y-extent = ##f
     }
   }
 }
@@ -2221,22 +2741,22 @@ select ancient accidentals.   Supported styles are
 As shown, not all accidentals are supported by each style.  When
 trying to access an unsupported accidental, LilyPond will switch to a
 different style, as demonstrated in
-@inputfileref{input/@/test,ancient@/-accidentals@/.ly}.
+@lsr{ancient,ancient-accidentals.ly}.
 
 Similarly to local accidentals, the style of the key signature can be
-controlled by the @code{style} property of the
+controlled by the @code{glyph-name-alist} property of the
 @internalsref{KeySignature} grob.
 
 @seealso
 
-In this manual: @ref{Pitches}, @ref{Cautionary accidentals} and
-@ref{Automatic accidentals} give a general introduction of the use of
-accidentals.  @ref{Key signature} gives a general introduction of
+In this manual: @ref{Pitches}, @ref{Cautionary accidentals}, and
+@ref{Automatic accidentals}, give a general introduction of the use of
+accidentals.  @ref{Key signature}, gives a general introduction of
 the use of key signatures.
 
 Program reference: @internalsref{KeySignature}.
 
-Examples: @inputfileref{input/@/test,ancient@/-accidentals@/.ly}.
+Examples: @lsrdir{ancient}
 
 @node Ancient rests
 @subsection Ancient rests
@@ -2255,7 +2775,7 @@ in historic prints of the 16th century.
 
 The following example demonstrates the @code{neomensural} style
 
-@lilypond[quote,fragment,raggedright,verbatim]
+@lilypond[quote,fragment,ragged-right,verbatim]
 \set Score.skipBars = ##t
 \override Rest #'style = #'neomensural
 r\longa r\breve r1 r2 r4 r8 r16
@@ -2263,15 +2783,15 @@ r\longa r\breve r1 r2 r4 r8 r16
 
 There are no 32th and 64th rests specifically for the mensural or
 neo-mensural style.  Instead, the rests from the default style will be
-taken.  See @inputfileref{input/@/test,rests@/.ly} for a chart of all
-rests.
+taken.  See @lsr{pitches,rests} for a chart of all rests.
 
 There are no rests in Gregorian Chant notation; instead, it uses
 @ref{Divisiones}.
 
 @seealso
 
-In this manual: @ref{Rests} gives a general introduction into the use of rests.
+In this manual: @ref{Rests}, gives a general introduction into the use of
+rests.
 
 
 @node Ancient clefs
@@ -2489,16 +3009,16 @@ historic style hufnagel combined do/fa clef
 
 
 
-@emph{Modern style} means ``as is typeset in contemporary editions of
-transcribed mensural music''.
+@emph{Modern style} means @qq{as is typeset in contemporary editions of
+transcribed mensural music.}
 
-@emph{Petrucci style} means ``inspired by printings published by the
-famous engraver Petrucci (1466-1539)''.
+@emph{Petrucci style} means @qq{inspired by printings published by the
+famous engraver Petrucci (1466-1539).}
 
-@emph{Historic style} means ``as was typeset or written in historic
-editions (other than those of Petrucci)''.
+@emph{Historic style} means @qq{as was typeset or written in historic
+editions (other than those of Petrucci).}
 
-@emph{Editio XXX style} means ``as is/was printed in Editio XXX''.
+@emph{Editio XXX style} means @qq{as is/was printed in Editio XXX.}
 
 Petrucci used C clefs with differently balanced left-side vertical
 beams, depending on which staff line it is printed.
@@ -2523,7 +3043,7 @@ Use the @code{flag-style} property of grob @internalsref{Stem} to
 select ancient flags.  Besides the @code{default} flag style,
 only the @code{mensural} style is supported
 
-@lilypond[quote,fragment,raggedright,verbatim]
+@lilypond[quote,fragment,ragged-right,verbatim]
 \override Stem #'flag-style = #'mensural
 \override Stem #'thickness = #1.0
 \override NoteHead #'style = #'mensural
@@ -2563,7 +3083,7 @@ to get a particular mensural signature glyph with the @code{\time n/m}
 command, @code{n} and @code{m} have to be chosen according to the
 following table
 
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
 \layout {
   indent = 0.0
   \context {
@@ -2576,25 +3096,35 @@ following table
 {
   \set Score.timing = ##f
   \set Score.barAlways = ##t
-  s_\markup { "\\time 4/4" }^\markup { "       " \musicglyph #"timesig.neomensural44" }
+  s_\markup { "\\time 4/4" }^\markup { "       " \musicglyph
+#"timesig.neomensural44" }
   s
-  s_\markup { "\\time 2/2" }^\markup { "       " \musicglyph #"timesig.neomensural22" }
+  s_\markup { "\\time 2/2" }^\markup { "       " \musicglyph
+#"timesig.neomensural22" }
   s
-  s_\markup { "\\time 6/4" }^\markup { "       " \musicglyph #"timesig.neomensural64" }
+  s_\markup { "\\time 6/4" }^\markup { "       " \musicglyph
+#"timesig.neomensural64" }
   s
-  s_\markup { "\\time 6/8" }^\markup { "       " \musicglyph #"timesig.neomensural68" }
+  s_\markup { "\\time 6/8" }^\markup { "       " \musicglyph
+#"timesig.neomensural68" }
   \break
-  s_\markup { "\\time 3/2" }^\markup { "       " \musicglyph #"timesig.neomensural32" }
+  s_\markup { "\\time 3/2" }^\markup { "       " \musicglyph
+#"timesig.neomensural32" }
   s
-  s_\markup { "\\time 3/4" }^\markup { "       " \musicglyph #"timesig.neomensural34" }
+  s_\markup { "\\time 3/4" }^\markup { "       " \musicglyph
+#"timesig.neomensural34" }
   s
-  s_\markup { "\\time 9/4" }^\markup { "       " \musicglyph #"timesig.neomensural94" }
+  s_\markup { "\\time 9/4" }^\markup { "       " \musicglyph
+#"timesig.neomensural94" }
   s
-  s_\markup { "\\time 9/8" }^\markup { "       " \musicglyph #"timesig.neomensural98" }
+  s_\markup { "\\time 9/8" }^\markup { "       " \musicglyph
+#"timesig.neomensural98" }
   \break
-  s_\markup { "\\time 4/8" }^\markup { "       " \musicglyph #"timesig.neomensural48" }
+  s_\markup { "\\time 4/8" }^\markup { "       " \musicglyph
+#"timesig.neomensural48" }
   s
-  s_\markup { "\\time 2/4" }^\markup { "       " \musicglyph #"timesig.neomensural24" }
+  s_\markup { "\\time 2/4" }^\markup { "       " \musicglyph
+#"timesig.neomensural24" }
 }
 @end lilypond
 
@@ -2607,7 +3137,7 @@ style mimics the look of historical printings of the 16th century.
 
 The following examples show the differences in style,
 
-@lilypond[raggedright,fragment,relative=1,quote]
+@lilypond[ragged-right,fragment,relative=1,quote]
 {
   \fatText
 
@@ -2633,7 +3163,7 @@ The following examples show the differences in style,
 
 @seealso
 
-This manual: @ref{Time signature} gives a general introduction to
+This manual: @ref{Time signature}, gives a general introduction to
 the use of time signatures.
 
 @refbugs
@@ -2664,20 +3194,18 @@ In addition to the standard articulation signs described in section
 provided.  These are specifically designed for use with notation in
 Editio Vaticana style.
 
-@lilypond[quote,raggedright,verbatim]
+@lilypond[quote,ragged-right,verbatim]
 \include "gregorian-init.ly"
 \score {
-  \context VaticanaVoice {
-    \override Staff.StaffSymbol #'color = #red
-    \override Staff.LedgerLineSpanner #'color = #red
+  \new VaticanaVoice {
     \override TextScript #'font-family = #'typewriter
     \override TextScript #'font-shape = #'upright
     \override Script #'padding = #-0.1
-    a4\ictus_"ictus" s1
-    a4\circulus_"circulus" s1
-    a4\semicirculus_"semicirculus" s1 s
-    a4\accentus_"accentus" s1
-    \[ a4_"episem" \episemInitium \pes b \flexa a \episemFinis \]
+    a\ictus_"ictus" \break
+    a\circulus_"circulus" \break
+    a\semicirculus_"semicirculus" \break
+    a\accentus_"accentus" \break
+    \[ a_"episem" \episemInitium \pes b \flexa a b \episemFinis \flexa a \]
   }
 }
 @end lilypond
@@ -2685,7 +3213,10 @@ Editio Vaticana style.
 @refbugs
 
 Some articulations are vertically placed too closely to the
-correpsonding note heads.
+corresponding note heads.
+
+The episem line is not displayed in many cases.  If it is displayed,
+the right end of the episem line is often too far to the right.
 
 @node Custodes
 @subsection Custodes
@@ -2693,7 +3224,7 @@ correpsonding note heads.
 @cindex custos
 @cindex custodes
 
-A @emph{custos} (plural: @emph{custodes}; Latin word for `guard') is a
+A @emph{custos} (plural: @emph{custodes}; Latin word for @q{guard}) is a
 symbol that appears at the end of a staff.  It anticipates the pitch
 of the first note(s) of the following line thus helping the performer
 to manage line breaks during performance.
@@ -2720,7 +3251,7 @@ as shown in the following example
 
 The result looks like this
 
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
 \score {
 {
   a'1
@@ -2738,7 +3269,7 @@ The custos glyph is selected by the @code{style} property.  The styles
 supported are @code{vaticana}, @code{medicaea}, @code{hufnagel}, and
 @code{mensural}.  They are demonstrated in the following fragment
 
-@lilypond[quote,raggedright,fragment]
+@lilypond[quote,ragged-right,fragment]
 \new Lyrics \lyricmode {
   \markup { \column {
     \typewriter "vaticana"
@@ -2763,7 +3294,8 @@ supported are @code{vaticana}, @code{medicaea}, @code{hufnagel}, and
 
 Program reference: @internalsref{Custos}.
 
-Examples: @inputfileref{input/@/regression,custos@/.ly}.
+Examples:
+@lsr{ancient,custodes@/.ly}.
 
 
 @node Divisiones
@@ -2774,7 +3306,7 @@ Examples: @inputfileref{input/@/regression,custos@/.ly}.
 @cindex finalis
 
 A @emph{divisio} (plural: @emph{divisiones}; Latin word for
-`division') is a staff context symbol that is used to structure
+@q{division}) is a staff context symbol that is used to structure
 Gregorian music into phrases and sections.  The musical meaning of
 @emph{divisio minima}, @emph{divisio maior}, and @emph{divisio maxima}
 can be characterized as short, medium, and long pause, somewhat like
@@ -2791,21 +3323,21 @@ and @code{\finalis} at proper places in the input.  Some editions use
 Therefore, @file{gregorian@/-init@/.ly} also defines @code{\virgula} and
 @code{\caesura}
 
-@lilypondfile[quote,raggedright]{divisiones.ly}
+@lilypondfile[quote,ragged-right]{divisiones.ly}
 
 @refcommands
 
-@cindex @code{\virgula}
+@funindex \virgula
 @code{\virgula},
-@cindex @code{\caesura}
+@funindex \caesura
 @code{\caesura},
-@cindex @code{\divisioMinima}
+@funindex \divisioMinima
 @code{\divisioMinima},
-@cindex @code{\divisioMaior}
+@funindex \divisioMaior
 @code{\divisioMaior},
-@cindex @code{\divisioMaxima}
+@funindex \divisioMaxima
 @code{\divisioMaxima},
-@cindex @code{\finalis}
+@funindex \finalis
 @code{\finalis}.
 
 @seealso
@@ -2814,7 +3346,8 @@ In this manual: @ref{Breath marks}.
 
 Program reference: @internalsref{BreathingSign}.
 
-Examples: @inputfileref{input/@/test,divisiones@/.ly}.
+Examples: @lsr{expressive,breathing-sign.ly}.
+
 
 @node Ligatures
 @subsection Ligatures
@@ -2834,7 +3367,7 @@ this particular type of ligature.  By default, the
 @internalsref{LigatureBracket} engraver just puts a square bracket
 above the ligature
 
-@lilypond[quote,raggedright,verbatim]
+@lilypond[quote,ragged-right,verbatim]
 \transpose c c' {
   \[ g c a f d' \]
   a g f
@@ -2859,8 +3392,6 @@ correctly align with ligatures.
 Accidentals must not be printed within a ligature, but instead need to
 be collected and printed in front of it.
 
-Augmentum dots within ligatures are not handled correctly.
-
 The syntax still uses the deprecated infix style @code{\[ music expr
 \]}.  For consistency reasons, it will eventually be changed to
 postfix style @code{note\[ ... note\]}.  Alternatively, the file
@@ -2916,14 +3447,11 @@ For example,
 \override Staff.TimeSignature #'style = #'neomensural
 \clef "petrucci-g"
 \[ c'\maxima g \]
-s4
 \[ d\longa c\breve f e d \]
-s4
 \[ c'\maxima d'\longa \]
-s4
 \[ e'1 a g\breve \]
 @end example
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
 \score {
   \transpose c c' {
     \set Score.timing = ##f
@@ -2932,11 +3460,8 @@ s4
     \override Staff.TimeSignature #'style = #'neomensural
     \clef "petrucci-g"
     \[ c'\maxima g \]
-    s4
     \[ d\longa c\breve f e d \]
-    s4
     \[ c'\maxima d'\longa \]
-    s4
     \[ e'1 a g\breve \]
   }
   \layout {
@@ -2953,7 +3478,7 @@ Without replacing @internalsref{Ligature_bracket_engraver} with
 @internalsref{Mensural_ligature_engraver}, the same music transcribes
 to the following
 
-@lilypond[quote,raggedright]
+@lilypond[quote,ragged-right]
 \transpose c c' {
   \set Score.timing = ##f
   \set Score.defaultBarType = "empty"
@@ -2961,19 +3486,15 @@ to the following
   \override Staff.TimeSignature #'style = #'neomensural
   \clef "petrucci-g"
   \[ c'\maxima g \]
-  s4
   \[ d\longa c\breve f e d \]
-  s4
   \[ c'\maxima d'\longa \]
-  s4
   \[ e'1 a g\breve \]
 }
 @end lilypond
 
 @refbugs
 
-The invisible rests (@code{s4}) in the example are used to compensate
-for the poor horizontal spacing.
+Horizontal spacing is poor.
 
 @node Gregorian square neumes ligatures
 @subsubsection Gregorian square neumes ligatures
@@ -3022,7 +3543,7 @@ Deminutae}
 @item
 @code{1. Punctum}
 @tab
-@lilypond[staffsize=26,linewidth=1.5\cm]
+@lilypond[staffsize=26,line-width=1.5\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3037,7 +3558,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=2.5\cm]
+@lilypond[staffsize=26,line-width=2.5\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3056,7 +3577,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3070,7 +3591,7 @@ Deminutae}
 @item
 @code{2. Virga}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3086,7 +3607,7 @@ Deminutae}
 @item
 @code{3. Apostropha vel Stropha}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3097,7 +3618,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3112,7 +3633,7 @@ Deminutae}
 @item
 @code{4. Oriscus}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3128,7 +3649,7 @@ Deminutae}
 @item
 @code{5. Clivis vel Flexa}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3139,7 +3660,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=2.0\cm]
+@lilypond[staffsize=26,line-width=2.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3154,7 +3675,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3168,7 +3689,7 @@ Deminutae}
 @item
 @code{6. Podatus vel Pes}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3179,7 +3700,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=2.0\cm]
+@lilypond[staffsize=26,line-width=2.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3194,7 +3715,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3208,7 +3729,7 @@ Deminutae}
 @item
 @code{7. Pes Quassus}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3219,7 +3740,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3234,7 +3755,7 @@ Deminutae}
 @item
 @code{8. Quilisma Pes}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3245,7 +3766,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3260,7 +3781,7 @@ Deminutae}
 @item
 @code{9. Podatus Initio Debilis}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3271,7 +3792,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3286,7 +3807,7 @@ Deminutae}
 @item
 @code{10. Torculus}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3297,7 +3818,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3308,7 +3829,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3322,7 +3843,7 @@ Deminutae}
 @item
 @code{11. Torculus Initio Debilis}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3333,7 +3854,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3344,7 +3865,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3358,7 +3879,7 @@ Deminutae}
 @item
 @code{12. Porrectus}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3369,7 +3890,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3380,7 +3901,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3394,7 +3915,7 @@ Deminutae}
 @item
 @code{13. Climacus}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3406,7 +3927,7 @@ Deminutae}
 }
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3417,7 +3938,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3431,7 +3952,7 @@ Deminutae}
 @item
 @code{14. Scandicus}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3442,7 +3963,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3453,7 +3974,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3467,7 +3988,7 @@ Deminutae}
 @item
 @code{15. Salicus}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3478,7 +3999,7 @@ Deminutae}
 \layout { \neumeDemoLayout }}
 @end lilypond
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3493,7 +4014,7 @@ Deminutae}
 @item
 @code{16. Trigonus}
 @tab
-@lilypond[staffsize=26,linewidth=1.0\cm]
+@lilypond[staffsize=26,line-width=1.0\cm]
 \include "gregorian-init.ly"
 \score {
   \transpose c c' {
@@ -3847,40 +4368,85 @@ Trigonus
 @code{\[ \stropha b \stropha b \stropha a \]}
 @end multitable
 
+The ligatures listed above mainly serve as a limited, but still
+representative pool of Gregorian ligature examples.  Virtually, within
+the ligature delimiters @code{\[} and @code{\]}, any number of heads
+may be accumulated to form a single ligature, and head prefixes like
+@code{\pes}, @code{\flexa}, @code{\virga}, @code{\inclinatum},
+etc. may be mixed in as desired.  The use of the set of rules that
+underlies the construction of the ligatures in the above table is
+accordingly extrapolated.  This way, infinitely many different
+ligatures can be created.
+
+Augmentum dots, also called @emph{morae}, are added with the music
+function @code{\augmentum}.  Note that @code{\augmentum} is
+implemented as a unary music function rather than as head prefix.  It
+applies to the immediately following music expression only.  That is,
+@code{\augmentum \virga c} will have no visible effect.  Instead, say
+@code{\virga \augmentum c} or @code{\augmentum @{\virga c@}}.  Also
+note that you can say @code{\augmentum @{a g@}} as a shortcut for
+@code{\augmentum a \augmentum g}.
+
+@lilypond[quote,ragged-right,verbatim]
+\include "gregorian-init.ly"
+\score {
+  \new VaticanaVoice {
+    \[ \augmentum a \flexa \augmentum g \]
+    \augmentum g
+  }
+}
+@end lilypond
+
 @refcommands
 
 The following head prefixes are supported
 
-@cindex @code{\virga}
+@funindex \virga
 @code{\virga},
-@cindex @code{\stropha}
+@funindex \stropha
 @code{\stropha},
-@cindex @code{\inclinatum}
+@funindex \inclinatum
 @code{\inclinatum},
-@cindex @code{\auctum}
+@funindex \auctum
 @code{\auctum},
-@cindex @code{\descendens}
+@funindex \descendens
 @code{\descendens},
-@cindex @code{\ascendens}
+@funindex \ascendens
 @code{\ascendens},
-@cindex @code{\oriscus}
+@funindex \oriscus
 @code{\oriscus},
-@cindex @code{\quilisma}
+@funindex \quilisma
 @code{\quilisma},
-@cindex @code{\deminutum}
-@code{\deminutum}.
+@funindex \deminutum
+@code{\deminutum},
+@funindex \cavum
+@code{\cavum},
+@funindex \linea
+@code{\linea}.
 
 Head prefixes can be accumulated, though restrictions apply.  For
 example, either @code{\descendens} or @code{\ascendens} can be applied
 to a head, but not both to the same head.
 
-@cindex @code{\pes}
-@cindex @code{\flexa}
+@funindex \pes
+@funindex \flexa
 Two adjacent heads can be tied together with the @code{\pes} and
 @code{\flexa} infix commands for a rising and falling line of melody,
 respectively.
 
+@funindex \augmentum
+Use the unary music function @code{\augmentum} to add augmentum dots.
+
+@refbugs
+
+When an @code{\augmentum} dot appears at the end of the last staff
+within a ligature, it is sometimes vertically placed wrong.  As a
+workaround, add an additional skip note (e.g. @code{s8}) as last note
+of the staff.
 
+@code{\augmentum} should be implemented as a head prefix rather than a
+unary music function, such that @code{\augmentum} can be intermixed
+with head prefixes in arbitrary order.
 
 @node Gregorian Chant contexts
 @subsection Gregorian Chant contexts
@@ -3895,24 +4461,20 @@ initialize all relevant context properties and grob properties to
 proper values, so you can immediately go ahead entering the chant, as
 the following excerpt demonstrates
 
-@lilypond[quote,raggedright,packed,verbatim]
+@lilypond[quote,ragged-right,packed,verbatim]
 \include "gregorian-init.ly"
 \score {
   <<
-    \context VaticanaVoice = "cantus" {
-      \override Staff.StaffSymbol #'color = #red
-      \override Staff.LedgerLineSpanner #'color = #red
-      \override Score.BarNumber #'transparent = ##t {
-        \[ c'\melisma c' \flexa a \]
-        \[ a \flexa \deminutum g\melismaEnd \]
-        f \divisioMinima
-        \[ f\melisma \pes a c' c' \pes d'\melismaEnd \]
-        c' \divisioMinima \break
-        \[ c'\melisma c' \flexa a \]
-        \[ a \flexa \deminutum g\melismaEnd \] f \divisioMinima
-      }
+    \new VaticanaVoice = "cantus" {
+      \[ c'\melisma c' \flexa a \]
+      \[ a \flexa \deminutum g\melismaEnd \]
+      f \divisioMinima
+      \[ f\melisma \pes a c' c' \pes d'\melismaEnd \]
+      c' \divisioMinima \break
+      \[ c'\melisma c' \flexa a \]
+      \[ a \flexa \deminutum g\melismaEnd \] f \divisioMinima
     }
-    \lyricsto "cantus" \new Lyrics {
+    \new Lyrics \lyricsto "cantus" {
       San- ctus, San- ctus, San- ctus
     }
   >>
@@ -3932,10 +4494,10 @@ style.  These contexts initialize all relevant context properties and
 grob properties to proper values, so you can immediately go ahead
 entering the chant, as the following excerpt demonstrates
 
-@lilypond[quote,raggedright,verbatim]
+@lilypond[quote,ragged-right,verbatim]
 \score {
   <<
-    \context MensuralVoice = "discantus" \transpose c c' {
+    \new MensuralVoice = "discantus" \transpose c c' {
       \override Score.BarNumber #'transparent = ##t {
         c'1\melisma bes a g\melismaEnd
         f\breve
@@ -3945,7 +4507,7 @@ entering the chant, as the following excerpt demonstrates
         fis\longa^\signumcongruentiae
       }
     }
-    \lyricsto "discantus" \new Lyrics {
+    \new Lyrics \lyricsto "discantus" {
       San -- ctus, San -- ctus, San -- ctus
     }
   >>
@@ -3957,21 +4519,22 @@ entering the chant, as the following excerpt demonstrates
 
 In European music from before about 1600, singers were often expected
 to chromatically alter notes at their own initiative. This is called
-``Musica Ficta''. In modern transcriptions, these accidentals are
+@q{Musica Ficta}. In modern transcriptions, these accidentals are
 usually printed over the note.
 
+@cindex Accidental, musica ficta
 @cindex Musica ficta
 
 Support for such suggested accidentals is included, and can be
 switched on by setting @code{suggestAccidentals} to true.
 
-@cindex @code{suggestAccidentals}
+@funindex suggestAccidentals
 
 @lilypond[verbatim,fragment,relative=1]
 fis gis
 \set suggestAccidentals = ##t
 ais bis
-@end lilypond 
+@end lilypond
 
 @seealso
 
@@ -3988,13 +4551,13 @@ Program reference: @internalsref{Accidental_engraver} engraver and the
 
 LilyPond has support for figured bass
 
-@lilypond[quote,raggedright,verbatim,fragment]
+@lilypond[quote,ragged-right,verbatim,fragment]
 <<
-  \context Voice { \clef bass dis4 c d ais g fis}
-  \context FiguredBass \figuremode {
-    < 6 >4 < 7 >8 < 6+ [_!] >
+  \new Voice { \clef bass dis4 c d ais g fis}
+  \new FiguredBass \figuremode {
+    < 6 >4 < 7\+ >8 < 6+ [_!] >
     < 6 >4 <6 5 [3+] >
-    < _ >4 < 6 >4
+    < _ >4 < 6 5/>4
   }
 >>
 @end lilypond
@@ -4009,61 +4572,68 @@ In figures input mode, a group of bass figures is delimited by
 @example
 <4 6>
 @end example
-@lilypond[quote,raggedright,fragment]
-\context FiguredBass
+@lilypond[quote,ragged-right,fragment]
+\new FiguredBass
 \figuremode { <4 6> }
 @end lilypond
 
 Accidentals are added when you append @code{-}, @code{!}, and @code{+}
-to the numbers
+to the numbers.  A plus sign is added when you append @code{\+}, and
+diminished fifths and sevenths can be obtained with @code{5/} and @code{7/}.
 
 @example
-<4- 6+ 7!>
+<4- 6+ 7!> <5++> <3--> <7/> r <6\+ 5/>
 @end example
-@lilypond[quote,raggedright,fragment]
-\context FiguredBass
-\figuremode { <4- 6+ 7!> }
+@lilypond[quote,ragged-right,fragment]
+\figures { <4- 6+ 7!> <5++> <3--> <7/> r <6\+ 5/> }
 @end lilypond
 
-Spaces or dashes may be inserted by using @code{_}.  Brackets are
+Spaces may be inserted by using @code{_}.  Brackets are
 introduced with @code{[} and @code{]}. You can also include text
 strings and text markups, see @ref{Overview of text markup commands}.
 
 @example
-< [4 6] 8 [_! 12] > < 5 \markup @{ + \number 6 @} >
+< [4 6] 8 [_! 12] > < 5 \markup @{ \number 6 \super (1) @} >
 @end example
-@lilypond[quote,raggedright,fragment]
-\context FiguredBass
-\figuremode { < [4 6] 8 [_! 12] > < 5 \markup{ + \number 6 } > }
+@lilypond[quote,ragged-right,fragment]
+\new FiguredBass
+\figuremode { < [4 6] 8 [_! 12] > < 5 \markup{ \tiny \number 6 \super (1)} > }
 @end lilypond
 
+
 It is also possible to use continuation lines for repeated figures,
 
 @lilypond[verbatim,relative=1]
 <<
-  \new Staff { c4 c }
+  \new Staff {
+    \clef bass
+    c4 c c
+  }
   \figures {
-    \set useBassFigureExtenders = ##t 
+    \set useBassFigureExtenders = ##t
     <4 6> <3 6> <3 7>
   }
 >>
 @end lilypond
 
+@noindent
+In this case, the extender lines always replace existing figures.
+
 The @code{FiguredBass} context doesn't pay attention to the actual
 bass line. As a consequence, you may have to insert extra figures to
-get extender lines below all notes, eg.
-
+get extender lines below all notes, and you may have to add @code{\!}
+to avoid getting an extender line, e.g.
 
-@lilypond[verbatim, relative=1]
+@lilypond[relative=1]
 <<
-  \new Voice 
+  \new Voice
+  \figures {
+    \set useBassFigureExtenders = ##t
+    <6 4->4. <6 4->16. <6 4->32 <5>8. r16 <6>8 <6\! 5->
+  }
   {
     \clef bass
-    f16. g32 f16. g32 f16. g32 f16. g32
-  }
-  \figures {
-    \set useBassFigureExtenders = ##t 
-    <6 4>4. <6 4>16. <6 4>32 <5 3>8 r
+    f16. g32 f16. g32 f16. g32 f16. g32 f8. es16 d8 es
   }
 >>
 @end lilypond
@@ -4071,18 +4641,35 @@ get extender lines below all notes, eg.
 When using continuation lines, common figures are always put in the
 same vertical position. When this is unwanted, you can insert a rest
 with @code{r}. The rest will clear any previous alignment.  For
-example, you can write 
+example, you can write
 
 @example
   <4 6>8 r8
 @end example
 
 @noindent
-instead of 
+instead of
 @example
   <4 6>4
 @end example
 
+Accidentals and plus signs can appear before or after the numbers,
+depending on the @code{figuredBassAlterationDirection} and
+@code{figuredBassPlusDirection}
+properties
+
+@lilypond
+  \figures {
+    <6\+> <5+> <6 4-> r
+    \set figuredBassAlterationDirection = #1
+    <6\+> <5+> <6 4-> r
+    \set figuredBassPlusDirection = #1
+    <6\+> <5+> <6 4-> r
+    \set figuredBassAlterationDirection = #-1
+    <6\+> <5+> <6 4-> r
+  }
+@end lilypond
+
 
 Although the support for figured bass may superficially resemble chord
 support, it is much simpler.  The @code{\figuremode} mode simply
@@ -4094,6 +4681,49 @@ Internally, the code produces markup texts.  You can use any of the
 markup text properties to override formatting.  For example, the
 vertical spacing of the figures may be set with @code{baseline-skip}.
 
+
+Figured bass can also be added to @code{Staff} contexts
+directly.  In this case, their vertical position is adjusted
+automatically.
+
+@lilypond[ragged-right,fragment,quote]
+<<
+  \new Staff = someUniqueName
+  \relative c'' {
+    c4 c'8 r8 c,4 c'
+  }
+
+  %% send to existing Staff.
+  \context Staff = someUniqueName 
+  \figuremode {
+    <4>4 <6 10>8 s8
+    
+    \set Staff.useBassFigureExtenders = ##t
+    <4 6>4 <4 6>
+  }
+>>
+@end lilypond
+
+
+@commonprop
+
+By default, this method produces figures above the notes.  To get
+figures below the notes, use
+
+@example
+\override Staff.BassFigureAlignmentPositioning #'direction = #DOWN
+@end example
+
+
+@refbugs
+
+When using figured bass above the staff with extender lines and
+@code{implicitBassFigures} the lines may become swapped around.
+Maintaining order consistently will be impossible when multiple figures
+have overlapping extender lines.  To avoid this problem, please
+use @code{stacking-dir} on @code{BassFigureAlignment}.
+
+
 @seealso
 
 Program reference: @internalsref{NewBassFigure},
@@ -4102,10 +4732,6 @@ Program reference: @internalsref{NewBassFigure},
 @internalsref{BassFigureContinuation} objects and
 @internalsref{FiguredBass} context.
 
-@refbugs
-
-Slash notation for alterations is not supported.
-
 
 
 @node Other instrument specific notation
@@ -4125,7 +4751,7 @@ This section includes extra information for writing for instruments.
 Artificial harmonics are notated with a different notehead style.  They
 are entered by marking the harmonic pitch with @code{\harmonic}.
 
-@lilypond[raggedright,verbatim,quote,fragment,relative=1]
+@lilypond[ragged-right,verbatim,quote,fragment,relative=1]
 <c g'\harmonic>4
 @end lilypond