X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Finstrument-notation.itely;h=f17aad795354deecdd2287ea314c1602964ca4e6;hb=c3ff1c6cd20e15e9036ee7120012e05b1d62a46d;hp=020e1c3b882cb0752ff86d2ffa62b4572a31be27;hpb=662c715cc4b57eeb4ec4da21e40a6d839e4368c3;p=lilypond.git

diff --git a/Documentation/user/instrument-notation.itely b/Documentation/user/instrument-notation.itely
index 020e1c3b88..f17aad7953 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
 
@@ -44,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
@@ -148,7 +150,7 @@ usually the setup for a score will start with a setup of the staves,
 and the @context{Voice} is inserted afterwards
 
 @example
-\new Staff = down
+\context Staff = down
   \new Voice @{ @dots{} \change Staff = up @dots{} @}
 @end example
 
@@ -197,7 +199,7 @@ 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.
 
@@ -229,7 +231,7 @@ 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
@@ -253,9 +255,9 @@ Program reference: @internalsref{VoiceFollower}.
 
 @refcommands
 
-@cindex @code{\showStaffSwitch}
+@funindex \showStaffSwitch
 @code{\showStaffSwitch},
-@cindex @code{\hideStaffSwitch}
+@funindex \hideStaffSwitch
 @code{\hideStaffSwitch}.
 
 
@@ -267,7 +269,10 @@ of the stem in the lower staff, so it reaches the stem in the upper
 staff, or vice versa.
 
 @lilypond[ragged-right,verbatim,quote]
-stemExtend = \once \override Stem #'length = #22
+stemExtend = {
+  \once \override Stem #'length = #10
+  \once \override Stem #'cross-staff = ##t
+}
 noFlag = \once \override Stem #'flag-style = #'no-flag
 \new PianoStaff <<
   \new Staff {
@@ -356,7 +361,7 @@ 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
 @lilypond[quote,fragment,verbatim]
@@ -413,11 +418,11 @@ 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
@@ -426,7 +431,7 @@ explicitly)
 \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
@@ -434,7 +439,7 @@ as bass notes, can be specified by appending
 @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,
 by using @code{/+}@var{pitch}.
@@ -512,8 +517,8 @@ for showing repeats.
   \consists "Volta_engraver"
 }
 \chordmode { \repeat volta 2 {
-  f1:maj f:7 bes:7
-  c:maj
+  f1:maj7 f:7 bes:7
+  c:maj7
 } \alternative {
   es e
 }
@@ -526,7 +531,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.
 
@@ -555,14 +560,14 @@ For an example of tuning this property, see also
 @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.
 
-@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
@@ -576,31 +581,31 @@ 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,
 
@@ -619,13 +624,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}.
 
 
@@ -687,12 +692,12 @@ way is to use the @code{\addlyrics} function.
 
 @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 
+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 
+\override Score.PaperColumn #'keep-inside-line = ##t
 @end example
 
 To make lyrics avoid barlines as well, use
@@ -737,7 +742,7 @@ More stanzas can be added by adding more
 \addlyrics { joue le jeu }
 @end lilypond
 
-The command @code{\addlyrics} cannot handle polyphony settings.  For these 
+The command @code{\addlyrics} cannot handle polyphony settings.  For these
 cases you should use @code{\lyricsto} and @code{\lyricmode}.
 
 
@@ -746,7 +751,7 @@ cases you should use @code{\lyricsto} and @code{\lyricmode}.
 @subsection Entering lyrics
 
 @cindex lyrics
-@cindex @code{\lyricmode}
+@funindex \lyricmode
 @cindex punctuation
 
 Lyrics are entered in a special input mode.  This mode is introduced
@@ -765,19 +770,20 @@ 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}.  For more details see @ref{The Lyrics context}.
 
-A word or syllable of lyrics begins with an alphabetic character, and ends 
+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 
+usually a mistake in the input file.  The syllable includes a @code{@}}, so
 the
 opening brace is not balanced
 @example
 \lyricmode @{ twinkle@}
 @end example
 
-@cindex @code{\property}, in @code{\lyricmode}
+@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
@@ -786,28 +792,37 @@ property commands
 \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 must
-surround them with quotes or use a @code{_} character between the syllables.
+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 ties is implemented with the Unicode character U+203F, so be
+sure to have a font (Like DejaVuLGC) installed that includes this
+glyph.
+
+
 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.
 
-@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,
@@ -827,6 +842,23 @@ 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 indentifiers 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
 
@@ -839,7 +871,7 @@ Program reference: @internalsref{LyricText}, @internalsref{LyricSpace}.
 
 @cindex hyphens
 
-Centered hyphens are entered as `@code{--}' between syllables.
+Centered hyphens are entered as @samp{--} between syllables.
 The hyphen will have variable length depending on the space between
 the syllables and it will be centered between the syllables.
 
@@ -849,7 +881,7 @@ the syllables and it will be centered between the syllables.
 When a lyric is sung over many notes (this is called a melisma), this is
 indicated with a horizontal line centered between a syllable and the
 next one.  Such a line is called an extender line, and it is entered as
-`@code{__}'.
+@samp{__}.
 
 In tighly engraved music, hyphens can be removed.  Whether this
 happens can be controlled with the @code{minimum-distance} (minimum
@@ -865,7 +897,7 @@ Program reference: @internalsref{LyricHyphen}, @internalsref{LyricExtender}.
 @node The Lyrics context
 @subsection The Lyrics context
 
-Lyrics are printed by interpreting them in the context caleld 
+Lyrics are printed by interpreting them in the context called
 @internalsref{Lyrics}.
 
 @example
@@ -873,7 +905,7 @@ Lyrics are printed by interpreting them in the context caleld
 @end example
 
 @cindex automatic syllable durations
-@cindex @code{\lyricsto}
+@funindex \lyricsto
 @cindex lyrics and melodies
 
 This will place the lyrics according to the durations that were
@@ -887,8 +919,8 @@ melody and the lyrics with the @code{\lyricsto} expression
 @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.
@@ -896,14 +928,14 @@ then the lyrics are specified with @code{\lyricsto}.  The command
 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 
+    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 Sav -- our reigns. }
+  \new Lyrics \lyricmode { Joy to the earth! the Sa -- viour reigns. }
   \new Lyrics \lyricsto "one" { No more let sins and sor -- rows grow. }
 >>
 @end lilypond
@@ -911,31 +943,9 @@ The following example uses different commands for entering lyrics.
 The second stanza is not properly aligned because the durations
 were not specified.  A solution for that would be to use @code{\lyricsto}.
 
-
-
-
-
-
-To define indentifiers 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
-
 The @code{\addlyrics} command is actually just a convenient way
 to write a more complicated LilyPond structure that sets up the
-lyrics. 
+lyrics.
 
 @example
 @{ MUSIC @}
@@ -1024,8 +1034,8 @@ 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
 
@@ -1091,10 +1101,11 @@ differing ways.  Such variations can still be captured with
 * Divisi lyrics::               
 * Switching the melody associated with a lyrics line::  
 * Specifying melismata within the lyrics::  
+* Lyrics independent of notes::  
 @end menu
 
 @node Lyrics to multiple notes of a melisma
-@subsubsection 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
@@ -1106,7 +1117,9 @@ 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,
 
+@c  FIXME: breaks compile
 @lilypond[verbatim,ragged-right,quote]
+%{
 <<
   \relative \new Voice = "lahlah" {
     \set Staff.autoBeaming = ##f
@@ -1125,11 +1138,12 @@ in the text, as shown here,
     still
   }
 >>
+%}
 @end lilypond
 
 
-The @code{ignoreMelismata} applies to the syllable ``fas'', so it
-should be entered before ``go''.
+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
@@ -1235,7 +1249,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" @{
@@ -1245,7 +1259,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
@@ -1255,7 +1269,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
@@ -1279,25 +1293,45 @@ The underlay is switched back to the starting situation by assigning
 
 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. 
+melisma.
 
-@lilypond[relative=1,verbatim,fragment] 
+@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
+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.
 
-@lilypond[relative=1,verbatim,fragment]
-{
- \set melismaBusyProperties = #'()
-  c d( e) f f( e) e e
+
+@node Lyrics independent of notes
+@subsubsection Lyrics independent of notes
+
+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[quote,verbatim,ragged-right]
+voice = {
+  c''2
+  \tag #'music { c''2 }
+  \tag #'lyricrhythm { c''4. c''8 }
+  d''1
 }
-\addlyrics
- { Ky -- _ _ ri __ _ _ _  e }
+
+lyr = \lyricmode { I like my cat! }
+
+<<
+  \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
 
 
@@ -1311,7 +1345,7 @@ To increase the spacing between lyrics, set the minimum-distance property of
 LyricSpace.
 
 @lilypond[relative,verbatim,fragment,quote,ragged-right]
-{ 
+{
   c c c c
   \override Lyrics.LyricSpace #'minimum-distance = #1.0
   c c c c
@@ -1322,7 +1356,7 @@ LyricSpace.
 }
 @end lilypond
 
-To make this change for all lyrics in the score, set the property in the 
+To make this change for all lyrics in the score, set the property in the
 layout.
 
 @lilypond[relative,verbatim,quote,ragged-right]
@@ -1348,12 +1382,11 @@ layout.
 @node More about stanzas
 @subsection More about stanzas
 
+@c what's this doing here?
 @cindex phrasing, in lyrics
 
-
 @cindex stanza number
-@cindex singer's names
-@cindex name of singer
+@subsubsection Adding stanza numbers 
 
 Stanza numbers can be added by setting @code{stanza}, e.g.,
 
@@ -1369,7 +1402,57 @@ Stanza numbers can be added by setting @code{stanza}, e.g.,
 }
 @end lilypond
 
-These numbers are put just before the start of first syllable.
+@noindent
+These numbers are put just before the start of the first syllable.
+
+
+@subsubsection Adding dynamics marks
+
+Stanzas differing in loudness may be indicated by putting a
+dynamics mark before each stanza.  In Lilypond, everthing coming in
+front of a stanza goes into the @code{StanzaNumber} object; dynamics marks
+are no different.  For technical reasons, you have to set the stanza
+outside @code{\lyricmode}:
+
+@lilypond[quote,ragged-right,verbatim]
+text = {
+  \set stanza = \markup { \dynamic "ff" "1. " }
+  \lyricmode {
+    Big bang
+  }
+}
+
+<<
+  \new Voice = "tune" {
+    \time 3/4
+    g'4 c'2
+  }
+\new Lyrics \lyricsto "tune" \text
+>>
+@end lilypond
+
+@cindex singer name
+@cindex name of singer
+@subsubsection Adding singer names
+
+Names of singers can also be added.  They are printed at the start of
+the line, just like instrument names.  They are created by setting
+@code{vocalName}.  A short version may be entered as @code{shortVocalName}.
+
+@lilypond[fragment,ragged-right,quote,verbatim,relative=2]
+\new Voice {
+  \time 3/4 g2 e4 a2 f4 g2.
+} \addlyrics {
+  \set vocalName = "Bert "
+  Hi, my name is Bert.
+} \addlyrics {
+  \set vocalName = "Ernie "
+  Oh, che -- ri, je t'aime
+}
+@end lilypond
+
+
+@subsubsection Printing stanzas at the end 
 
 Sometimes it is appropriate to have one stanza set
 to the music, and the rest added in verse form at
@@ -1415,27 +1498,77 @@ its fleece was white as snow.
 @end lilypond
 
 
-Names of singers can also be added.  They are printed at the start of
-the line, just like instrument names.  They are created by setting
-@code{vocalName}.  A short version may be entered as @code{vocNam}.
+@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[fragment,ragged-right,quote,verbatim,relative=2]
-\new Voice {
-  \time 3/4 g2 e4 a2 f4 g2.
-} \addlyrics {
-  \set vocalName = "Bert "
-  Hi, my name is Bert.
-} \addlyrics {
-  \set vocalName = "Ernie "
-  Oh, che -- ri, je t'aime
+@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.
+}
+
+\score{ <<
+    \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}, 
+Program reference: @internalsref{LyricText}, @internalsref{StanzaNumber},
 @internalsref{VocalName}.
 
 
@@ -1544,7 +1677,7 @@ 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}.
 
@@ -1562,6 +1695,7 @@ also be used to show the rhythms of melodies.
 * Showing melody rhythms::      
 * Entering percussion::         
 * Percussion staves::           
+* Ghost notes::                 
 @end menu
 
 
@@ -1635,7 +1769,7 @@ 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,ragged-right,fragment,verbatim]
@@ -1828,6 +1962,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
@@ -1841,6 +2011,7 @@ for this purpose instead.
 * Non-guitar tablatures::       
 * Banjo tablatures::            
 * Fret diagrams::               
+* Right hand fingerings::       
 * Other guitar issues::         
 @end menu
 
@@ -1850,7 +2021,7 @@ 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,ragged-right,fragment]
 <c\1 e\2 g\3>
@@ -1887,7 +2058,7 @@ are printed as tablature, by using @internalsref{TabStaff} and
 }
 @end lilypond
 
-@cindex @code{minimumFret}
+@funindex minimumFret
 @cindex fret
 
 When no string is specified, the first string that does not give a
@@ -1966,14 +2137,14 @@ and bass guitar.
 \set TabStaff.stringTunings = #bass-tuning
 @end example
 
-The default string tuning is @code{guitar-tuning} (the standard EADGBE 
+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 
+The file @file{scm/@/output@/-lib@/.scm} contains the predefined string
 tunings.
 Program reference: @internalsref{Tab_note_heads_engraver}.
 
@@ -1988,7 +2159,7 @@ No guitar special effects have been implemented.
 @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 
+for five stringed banjo, use the banjo tablature format function to get
 correct
 fret numbers for the fifth string:
 
@@ -2071,6 +2242,62 @@ Details about the property interface to fret diagrams are found at
 Examples: @inputfileref{input/@/test,fret@/-diagram@/.ly}
 
 
+@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
+
+Internalls: @internalsref{StrokeFinger}
+
+
+
 @node Other guitar issues
 @subsection Other guitar issues
 
@@ -2088,9 +2315,9 @@ 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}.
@@ -2135,16 +2362,16 @@ notes in the appropiate octaves, so you do not need to worry about
 { \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.
 
 
@@ -2170,7 +2397,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
@@ -2294,8 +2521,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}
@@ -2341,9 +2567,9 @@ 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,ragged-right,staffsize=26]
 \score {
@@ -2390,7 +2616,7 @@ different style, as demonstrated in
 @inputfileref{input/@/test,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
@@ -2437,7 +2663,7 @@ There are no rests in Gregorian Chant notation; instead, it uses
 
 @seealso
 
-In this manual: @ref{Rests} gives a general introduction into the use of 
+In this manual: @ref{Rests} gives a general introduction into the use of
 rests.
 
 
@@ -2656,16 +2882,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.
@@ -2743,34 +2969,34 @@ following table
 {
   \set Score.timing = ##f
   \set Score.barAlways = ##t
-  s_\markup { "\\time 4/4" }^\markup { "       " \musicglyph 
+  s_\markup { "\\time 4/4" }^\markup { "       " \musicglyph
 #"timesig.neomensural44" }
   s
-  s_\markup { "\\time 2/2" }^\markup { "       " \musicglyph 
+  s_\markup { "\\time 2/2" }^\markup { "       " \musicglyph
 #"timesig.neomensural22" }
   s
-  s_\markup { "\\time 6/4" }^\markup { "       " \musicglyph 
+  s_\markup { "\\time 6/4" }^\markup { "       " \musicglyph
 #"timesig.neomensural64" }
   s
-  s_\markup { "\\time 6/8" }^\markup { "       " \musicglyph 
+  s_\markup { "\\time 6/8" }^\markup { "       " \musicglyph
 #"timesig.neomensural68" }
   \break
-  s_\markup { "\\time 3/2" }^\markup { "       " \musicglyph 
+  s_\markup { "\\time 3/2" }^\markup { "       " \musicglyph
 #"timesig.neomensural32" }
   s
-  s_\markup { "\\time 3/4" }^\markup { "       " \musicglyph 
+  s_\markup { "\\time 3/4" }^\markup { "       " \musicglyph
 #"timesig.neomensural34" }
   s
-  s_\markup { "\\time 9/4" }^\markup { "       " \musicglyph 
+  s_\markup { "\\time 9/4" }^\markup { "       " \musicglyph
 #"timesig.neomensural94" }
   s
-  s_\markup { "\\time 9/8" }^\markup { "       " \musicglyph 
+  s_\markup { "\\time 9/8" }^\markup { "       " \musicglyph
 #"timesig.neomensural98" }
   \break
-  s_\markup { "\\time 4/8" }^\markup { "       " \musicglyph 
+  s_\markup { "\\time 4/8" }^\markup { "       " \musicglyph
 #"timesig.neomensural48" }
   s
-  s_\markup { "\\time 2/4" }^\markup { "       " \musicglyph 
+  s_\markup { "\\time 2/4" }^\markup { "       " \musicglyph
 #"timesig.neomensural24" }
 }
 @end lilypond
@@ -2845,16 +3071,14 @@ Editio Vaticana style.
 \include "gregorian-init.ly"
 \score {
   \new VaticanaVoice {
-    \override Staff.StaffSymbol #'color = #red
-    \override Staff.LedgerLineSpanner #'color = #red
     \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
@@ -2864,13 +3088,16 @@ Editio Vaticana style.
 Some articulations are vertically placed too closely to the
 correpsonding 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
 
 @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.
@@ -2951,7 +3178,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
@@ -2972,17 +3199,17 @@ Therefore, @file{gregorian@/-init@/.ly} also defines @code{\virgula} and
 
 @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
@@ -3036,8 +3263,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
@@ -3093,11 +3318,8 @@ 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,ragged-right]
@@ -3109,11 +3331,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 {
@@ -3138,19 +3357,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
@@ -4038,44 +4253,75 @@ ligatures can be created.
 @c even more Gregorian ligatures, and add a link to this document
 @c here.
 
+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}
+@funindex \deminutum
 @code{\deminutum},
-@cindex @code{\cavum}
+@funindex \cavum
 @code{\cavum},
-@cindex @code{\linea}
+@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
@@ -4095,17 +4341,13 @@ the following excerpt demonstrates
 \score {
   <<
     \new 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
-      }
+      \[ 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 Lyrics \lyricsto "cantus" {
       San- ctus, San- ctus, San- ctus
@@ -4152,21 +4394,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
 
@@ -4242,7 +4485,7 @@ It is also possible to use continuation lines for repeated figures,
     c4 c c
   }
   \figures {
-    \set useBassFigureExtenders = ##t 
+    \set useBassFigureExtenders = ##t
     <4 6> <3 6> <3 7>
   }
 >>
@@ -4250,7 +4493,7 @@ It is also possible to use continuation lines for repeated figures,
 
 @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, and you may have to add @code{\!}
@@ -4258,9 +4501,9 @@ to avoid getting an extender line, e.g.
 
 @lilypond[relative=1]
 <<
-  \new Voice 
+  \new Voice
   \figures {
-    \set useBassFigureExtenders = ##t 
+    \set useBassFigureExtenders = ##t
     <6 4->4. <6 4->16. <6 4->32 <5>8. r16 <6>8 <6\! 5->
   }
   {
@@ -4273,20 +4516,20 @@ to avoid getting an extender line, e.g.
 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 
+depending on the @code{figuredBassAlterationDirection} and
 @code{figuredBassPlusDirection}
 properties
 
@@ -4313,6 +4556,39 @@ 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
+
+
+@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, plese
+use @code{stacking-dir} on @code{BassFigureAlignment}.
+
+
 @seealso
 
 Program reference: @internalsref{NewBassFigure},