X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;ds=inline;f=Documentation%2Fuser%2Fchanging-defaults.itely;h=b63980e924431bc738d5dba35a20ff9a648fa636;hb=3eb1e37e2e0b3966142cd04b85e30ab882308612;hp=f18d137c792bf9444d17c3f4819423618ca13fdb;hpb=0bf10e418a7d6542d6e3a0c3e2dcf70b4ec61f70;p=lilypond.git

diff --git a/Documentation/user/changing-defaults.itely b/Documentation/user/changing-defaults.itely
index f18d137c79..b63980e924 100644
--- a/Documentation/user/changing-defaults.itely
+++ b/Documentation/user/changing-defaults.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.61"
+@c \version "2.12.0"
 
 @node Changing defaults
 @chapter Changing defaults
@@ -57,14 +57,15 @@ This section describes what contexts are, and how to modify them.
 @menu
 * Contexts explained::
 * Creating contexts::
+* Keeping contexts alive::
 * Modifying context plug-ins::
 * Changing context default settings::
 * Defining new contexts::
 * Aligning contexts::
 @end menu
 
-@seealso
 
+@seealso
 Learning Manual:
 @rlearning{Contexts and engravers}.
 
@@ -77,7 +78,7 @@ Snippets:
 
 Internals Reference:
 @rinternals{Contexts},
-@rinternals{Engravers and performers}.
+@rinternals{Engravers and Performers}.
 
 
 @node Contexts explained
@@ -108,7 +109,7 @@ further explanation and with links to the IR.
 
 @c TODO Describe propagation of property values -td
 
-Contexts are arranged heirarchically:
+Contexts are arranged hierarchically:
 
 @menu
 * Score - the master of all contexts::
@@ -138,67 +139,55 @@ executed.
 
 Groups staves while adding a bracket on the left side, grouping
 the staves together. The bar lines of the contained staves are
-connected vertically. StaffGroup only consists of a collection
+connected vertically.  @code{StaffGroup} only consists of a collection
 of staves, with a bracket in front and spanning bar lines.
 
 @strong{@emph{ChoirStaff}}
 
-Identical to StaffGroup except that the bar lines of the contained
-staves are not connected vertically.
+Identical to @code{StaffGroup} except that the bar lines of the
+contained staves are not connected vertically.
 
 @strong{@emph{GrandStaff}}
 
-A group of staves, with a brace on the left side, grouping
-the staves together. The bar lines of the contained staves are
+A group of staves, with a brace on the left side, grouping the
+staves together.  The bar lines of the contained staves are
 connected vertically.
 
 @strong{@emph{PianoStaff}}
 
-@c TODO No longer correct?  Check.  -td
-Just like GrandStaff but with a forced distance between the
-staves, so cross staff beaming and slurring can be used.
-
-@ignore
-@strong{@emph{InnerStaffGroup}}
-
-TODO  -td
-
-@strong{@emph{InnerChoirStaff}}
-
-TODO  -td
-
-@end ignore
+Just like @code{GrandStaff}, but with support for instrument names
+to the left of each system.
 
 @node Intermediate-level contexts - staves
 @unnumberedsubsubsec Intermediate-level contexts - staves
 
 @strong{@emph{Staff}}
 
-Handles clefs, bar lines, keys, accidentals. It can contain
-Voice contexts.
+Handles clefs, bar lines, keys, accidentals.  It can contain
+@code{Voice} contexts.
 
 @strong{@emph{RhythmicStaff}}
 
-Like Staff but for printing rhythms. Pitches are ignored;
+Like @code{Staff} but for printing rhythms.  Pitches are ignored;
 the notes are printed on one line.
 
 @strong{@emph{TabStaff}}
 
-Context for generating tablature. By default lays the music
+Context for generating tablature.  By default lays the music
 expression out as a guitar tablature, printed on six lines.
 
 @strong{@emph{DrumStaff}}
 
-Handles typesetting for percussion. Can contain DrumVoice
+Handles typesetting for percussion.  Can contain @code{DrumVoice}
 
 @strong{@emph{VaticanaStaff}}
 
-Same as Staff, except that it is designed for typesetting
+Same as @code{Staff}, except that it is designed for typesetting
 a piece in gregorian style.
 
 @strong{@emph{MensuralStaff}}
 
-Same as Staff, except that it is designed for typesetting
+Same as @code{Staff}, except that it is designed for typesetting
 a piece in mensural style.
 
 @node Bottom-level contexts - voices
@@ -210,24 +199,24 @@ contain other contexts.
 
 @strong{@emph{Voice}}
 
-Corresponds to a voice on a staff. This context handles the
+Corresponds to a voice on a staff.  This context handles the
 conversion of dynamic signs, stems, beams, super- and sub-scripts,
 slurs, ties, and rests.  You have to instantiate this explicitly
 if you require multiple voices on the same staff.
 
 @strong{@emph{VaticanaVoice}}
 
-Same as Voice, except that it is designed for typesetting a piece
-in gregorian style.
+Same as @code{Voice}, except that it is designed for typesetting
+a piece in gregorian style.
 
 @strong{@emph{MensuralVoice}}
 
-Same as Voice, with modifications for typesetting a piece in
+Same as @code{Voice}, with modifications for typesetting a piece in
 mensural style.
 
 @strong{@emph{Lyrics}}
 
-Corresponds to a voice with lyrics. Handles the printing of a
+Corresponds to a voice with lyrics.  Handles the printing of a
 single line of lyrics.
 
 @strong{@emph{DrumVoice}}
@@ -236,13 +225,13 @@ The voice context used in a percussion staff.
 
 @strong{@emph{FiguredBass}}
 
-The context in which BassFigure objects are created from
+The context in which @code{BassFigure} objects are created from
 input entered in @code{\figuremode} mode.
 
 @strong{@emph{TabVoice}}
 
-The voice context used within a TabStaff context.  Usually left to
-be created implicitly.
+The voice context used within a @code{TabStaff} context.  Usually
+left to be created implicitly.
 
 @strong{@emph{ChordNames}}
 
@@ -414,6 +403,156 @@ these forms
 
 @end itemize
 
+@node Keeping contexts alive
+@subsection Keeping contexts alive
+
+@cindex contexts, keeping alive
+@cindex contexts, lifetime
+
+Contexts are usually terminated at the first musical moment in
+which they have nothing to do.  So @code{Voice} contexts die as
+soon as they contain no events; @code{Staff} contexts die as soon
+as all the @code{Voice} contexts within them contain no events; etc.
+This can cause difficulties if earlier contexts which have died
+have to be referenced, for example, when changing staves with
+@code{\change} commands, associating lyrics with a voice with
+@code{\lyricsto} commands, or when adding further musical events to
+an earlier context.
+
+There is an exception to this general rule: just one of the
+@code{Voice} contexts in a @code{Staff} context or in a
+@code{<<...>>} construct will always persist to the end of the
+enclosing @code{Staff} context or @code{<<...>>} construct, even
+though there may be periods when it has nothing to do.  The context
+to persist in this way will be the first one encountered in the
+first enclosed @code{@{...@}} construct, ignoring any in enclosed
+@code{<<...>>} constructs.
+
+Any context can be kept alive by ensuring it has something to do at
+every musical moment.  @code{Staff} contexts are kept alive by
+ensuring one of their voices is kept alive.  One way of doing this
+is to add spacer rests to a voice in parallel with the real music.
+These need to be added to every @code{Voice} context which needs to
+be kept alive.  If several voices are to be used sporadically it is
+safest to keep them all alive rather than attempting to rely on the
+exceptions mentioned above.
+
+In the following example, both voice A and voice B are kept alive
+in this way for the duration of the piece:
+
+@lilypond[quote,verbatim]
+musicA = \relative c'' { d4 d d d }
+musicB = \relative c'' { g4 g g g }
+keepVoicesAlive = {
+  <<
+    \new Voice = "A" { s1*5 }  % Keep Voice "A" alive for 5 bars
+    \new Voice = "B" { s1*5 }  % Keep Voice "B" alive for 5 bars
+  >>
+}
+
+music = {
+  \context Voice = "A" {
+    \voiceOneStyle
+    \musicA
+  }
+  \context Voice = "B" {
+    \voiceTwoStyle
+    \musicB
+  }
+  \context Voice = "A" { \musicA }
+  \context Voice = "B" { \musicB }
+  \context Voice = "A" { \musicA }
+}
+
+\score {
+  \new Staff <<
+    \keepVoicesAlive
+    \music
+  >>
+}
+@end lilypond
+
+@cindex lyrics, aligning with sporadic melody
+
+The following example shows how a sporadic melody line with lyrics
+might be written using this approach.  In a real situation the
+melody and accompaniment would consist of several different
+sections, of course.
+
+@lilypond[quote,verbatim]
+melody = \relative c'' { a4 a a a }
+accompaniment = \relative c' { d4 d d d }
+words = \lyricmode { These words fol -- low the mel -- o -- dy }
+\score {
+  <<
+    \new Staff = "music" {
+      <<
+        \new Voice = "melody" {
+          \voiceOne
+          s1*4  % Keep Voice "melody" alive for 4 bars
+        }
+        {
+          \new Voice = "accompaniment" {
+            \voiceTwo
+            \accompaniment
+          }
+          <<
+            \context Voice = "melody" { \melody }
+            \context Voice = "accompaniment" { \accompaniment }
+          >>
+          \context Voice = "accompaniment" { \accompaniment }
+          <<
+            \context Voice = "melody" { \melody }
+            \context Voice = "accompaniment" { \accompaniment }
+          >>
+        }
+      >>
+    }
+    \new Lyrics \with { alignAboveContext = #"music" }
+    \lyricsto "melody" { \words }
+  >>
+}
+@end lilypond
+
+An alternative way, which may be better in many circumstances, is
+to keep the melody line alive by simply including spacer notes to
+line it up correctly with the accompaniment:
+
+@lilypond[quote,verbatim]
+melody = \relative c'' {
+  s1  % skip a bar
+  a4 a a a
+  s1  % skip a bar
+  a4 a a a
+}
+accompaniment = \relative c' {
+  d4 d d d
+  d4 d d d
+  d4 d d d
+  d4 d d d
+}
+words = \lyricmode { These words fol -- low the mel -- o -- dy }
+
+\score {
+  <<
+    \new Staff = "music" {
+      <<
+        \new Voice = "melody" {
+          \voiceOne
+          \melody
+        }
+        \new Voice = "accompaniment" {
+          \voiceTwo
+          \accompaniment
+        }
+      >>
+    }
+    \new Lyrics \with { alignAboveContext = #"music" }
+    \lyricsto "melody" { \words }
+  >>
+}
+@end lilypond
+
 
 @node Modifying context plug-ins
 @subsection Modifying context plug-ins
@@ -540,51 +679,38 @@ with ordering dependencies.
 @node Changing context default settings
 @subsection Changing context default settings
 
-The adjustments of the previous subsections (
-@ref{The set command}, @ref{Modifying context plug-ins}, and
-@ref{Overview of modifying properties}) can also be entered
-separately from the music in the @code{\layout} block,
+The context settings which are to be used by default in
+@code{Score}, @code{Staff} and @code{Voice} contexts may be specified
+in a @code{\layout} block, as illustrated in the following example.
+The @code{\layout} block should be placed within the @code{\score}
+block to which it is to apply, but outside any music.
 
-@example
-\layout @{
-  @dots{}
-  \context @{
-    \Staff
+Note that the @code{\set} command itself and the context must be
+omitted when the context default values are specified in this way:
 
-    \set fontSize = #-2
-    \override Stem #'thickness = #4.0
-    \remove "Time_signature_engraver"
-  @}
-@}
-@end example
-
-The @code{\Staff} command brings in the existing definition of the
-staff context so that it can be modified.
-
-The statements
-@example
-\set fontSize = #-2
-\override Stem #'thickness = #4.0
-\remove "Time_signature_engraver"
-@end example
-
-@noindent
-affect all staves in the score.  Other contexts can be modified
-analogously.
-
-The @code{\set} keyword is optional within the @code{\layout} block, so
-
-@example
-\context @{
-  @dots{}
-  fontSize = #-2
-@}
-@end example
-
-@noindent
-will also work.
+@lilypond[quote,verbatim]
+\score {
+  \relative c'' {
+    a4^"Really small, thicker stems, no time signature" a a a
+    a a a a
+  }
+  \layout {
+    \context {
+      \Staff
+      fontSize = #-4
+      \override Stem #'thickness = #4.0
+      \remove "Time_signature_engraver"
+    }
+  }
+}
+@end lilypond
 
+In this example, the @code{\Staff} command specifies that the
+subsequent specifications are to be applied to all staves within
+this score block.
 
+Modifications can be made to the @code{Score} context or all
+@code{Voice} contexts in a similar way.
 
 @knownissues
 
@@ -627,6 +753,7 @@ to indicate improvisation in jazz pieces,
   \name ImproVoice
   \type "Engraver_group"
   \consists "Note_heads_engraver"
+  \consists "Rhythmic_column_engraver"
   \consists "Text_engraver"
   \consists Pitch_squash_engraver
   squashedPosition = #0
@@ -782,8 +909,8 @@ in ossia,
 @c TODO Better example needed.  Ref LM, and expand on it.
 
 @cindex ossia
-@findex alignAboveContext
-@findex alignBelowContext
+@funindex alignAboveContext
+@funindex alignBelowContext
 
 @lilypond[quote,ragged-right]
 ossia = { f4 f f f }
@@ -791,23 +918,70 @@ ossia = { f4 f f f }
   \relative c' \new Staff = "main" {
     c4 c c c
     <<
-      \new Staff \with {alignAboveContext=main} \ossia
+      \new Staff \with { alignAboveContext = #"main" } \ossia
       { d8 f d f d f d f }
     >>
   }
 }
 @end lilypond
 
+@cindex nested contexts
+@cindex contexts, nested
+
+@funindex \accepts
+@funindex \denies
+
+Contexts like @code{PianoStaff} can contain other contexts
+nested within them.  Contexts which are acceptable for nesting
+are defined by the @qq{accepts} list of a context.  Contexts
+which are not in this list are placed below the outer context
+in the printed score.
+For example, the @code{PianoStaff} context is defined by default
+to accept @code{Staff} and @code{FiguredBass} contexts within
+it, but not (for example) a @code{Lyrics} context.  So in the
+following structure the lyrics are placed below the piano staff
+rather than between the two staves:
+
+@lilypond[verbatim,quote,relative=1]
+\new PianoStaff
+<<
+  \new Staff { e4 d c2 }
+  \addlyrics { Three blind mice }
+  \new Staff {
+    \clef "bass"
+    { c,1 }
+  }
+>>
+@end lilypond
+
+The @qq{accepts} list of a context can be modified to include
+additional nested contexts, so if we wanted the lyrics to appear
+between the two staves we could use:
+
+@lilypond[verbatim,quote,relative=1]
+\new PianoStaff \with { \accepts Lyrics }
+<<
+  \new Staff { e4 d c2 }
+  \addlyrics { Three blind mice }
+  \new Staff {
+    \clef "bass"
+    { c,1 }
+  }
+>>
+@end lilypond
+
+The opposite of @code{\accepts} is @code{\denies}; this removes a
+context from the @qq{accepts} list.
 
 @node Explaining the Internals Reference
 @section Explaining the Internals Reference
 
 
 @menu
-* Navigating the program reference::  
-* Layout interfaces::           
-* Determining the grob property::  
-* Naming conventions::          
+* Navigating the program reference::
+* Layout interfaces::
+* Determining the grob property::
+* Naming conventions::
 @end menu
 
 @node Navigating the program reference
@@ -1233,12 +1407,11 @@ properties.  To tweak those, use commands of the form
 such as
 
 @example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
+\override Stem #'(details beamed-lengths) = #'(4 4 3)
 @end example
 
 
 @seealso
-
 Internals: @rinternals{OverrideProperty}, @rinternals{RevertProperty},
 @rinternals{PropertySet}, @rinternals{Backend}, and
 @rinternals{All layout objects}.
@@ -1400,7 +1573,7 @@ Some tweakable options are called @q{subproperties} and reside inside
 properties.  To tweak those, use commands in the form
 
 @example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
+\override Stem #'(details beamed-lengths) = #'(4 4 3)
 @end example
 
 @cindex internal documentation
@@ -1459,7 +1632,7 @@ command to remain immediately adjacent to the object to which it is
 to apply after the input file has been converted to a music stream.
 This is often not the case, as many additional elements are inserted
 into the music stream implicitly.  For example, when a note which is
-not part of a chord is processed, Lilypond implicitly inserts a
+not part of a chord is processed, LilyPond implicitly inserts a
 @code{ChordEvent} event before the note, so separating the tweak
 from the note.  However, if chord symbols are placed round the
 tweak and the note, the @code{\tweak} command comes after the
@@ -1500,12 +1673,12 @@ and @code{\tweak} may be used to modify any single occurrence of
 these items.
 
 Notably the @code{\tweak} command cannot be used to modify stems,
-beams or accidentals, since these are generated later by note heads,
-rather than by music elements in the input stream.  Nor can a
-@code{\tweak} command be used to modify clefs or time signatures,
-since these become separated from any preceding @code{\tweak}
-command in the input stream by the automatic insertion of extra
-elements required to specify the context.
+beams or accidentals directly, since these are generated later by
+note heads, rather than by music elements in the input stream.
+Nor can a @code{\tweak} command be used to modify clefs or time
+signatures, since these become separated from any preceding
+@code{\tweak} command in the input stream by the automatic
+insertion of extra elements required to specify the context.
 
 But the @code{\tweak} command can be used as an alternative to
 the @code{\override} command to modify those notational elements
@@ -1535,14 +1708,15 @@ including any automatically inserted elements, may be examined,
 see @ref{Displaying music expressions}.  This may be helpful in
 determining what may be modified by a @code{\tweak} command.
 
-@seealso
 
+@seealso
 Learning Manual:
 @rlearning{Tweaking methods}.
 
 Notation Reference:
 @ref{Displaying music expressions}.
 
+
 @knownissues
 
 @cindex tweaks in a variable
@@ -1617,6 +1791,7 @@ property (modified with @code{\set}) was created.
 * Input modes::
 * Direction and placement::
 * Distances and measurements::
+* Staff symbol properties::
 * Spanners::
 * Visibility of objects::
 * Line styles::
@@ -1746,17 +1921,18 @@ up or down based on the stem direction (like slurs or accents).
 
 @c TODO Add table showing these
 
-@strong{Context layout}
+@strong{Context layout order}
 
-Contexts are positioned in a system from top to bottom in the
-order in which they are encountered.  Note, however, that a
-context will be created implicitly if a command is encountered
-when there is no suitable context available to contain it.
+Contexts are normally positioned in a system from top to bottom
+in the order in which they are encountered.  Note, however, that
+a context will be created implicitly if a command is encountered
+when there is no suitable context available to contain it.  When
+contexts are nested, the outer context will exclude inner contexts
+which are not included in its @qq{accepts} list; excluded contexts
+will be repositioned below the outer context.
 
-@c TODO Add example ?
-
-The default order in which contexts are laid out can be changed,
-see @ref{Aligning contexts}
+The default order in which contexts are laid out and the
+@qq{accepts} list can be changed, see @ref{Aligning contexts}.
 
 @strong{Articulation direction indicators}
 
@@ -1775,6 +1951,15 @@ indicator is @strong{always} required before
 @item articulation shortcuts, e.g. @code{-.}, @code{->}, @code{--}
 @end itemize
 
+These indications affect only the next note.
+
+@lilypond[verbatim,quote,relative=2]
+c2( c)
+c2_( c)
+c2( c)
+c2^( c)
+@end lilypond
+
 @strong{The direction property}
 
 The position or direction of many layout objects is controlled
@@ -1812,6 +1997,17 @@ TrillPitchAccidental - not tried
 TrillPitchGroup - not tried
 @end ignore
 
+These indications affect all notes until they are cancelled.
+
+@lilypond[verbatim,quote,relative=2]
+c2( c)
+\slurDown
+c2( c)
+c2( c)
+\slurNeutral
+c2( c)
+@end lilypond
+
 
 
 @node Distances and measurements
@@ -1862,8 +2058,8 @@ convert from a font size change to the equivalent change in
 @code{staff-space}.  For an explanation and an example of its use,
 see @rlearning{Length and thickness of objects}.
 
-@seealso
 
+@seealso
 Learning Manual:
 @rlearning{Length and thickness of objects}.
 
@@ -1872,6 +2068,46 @@ Notation Reference:
 @ref{Setting the staff size}.
 
 
+@node Staff symbol properties
+@subsection Staff symbol properties
+
+@cindex adjusting staff symbol
+@cindex drawing staff symbol
+@cindex staff symbol, setting of
+
+@c TODO Extend or remove this section.  See also NR 1.6.2 Staff symbol
+@c      Need to think of uses for these properties.  Eg 'line-positions
+@c      is used in a snippet to thicken centre line.
+@c      If retained, add @ref to here in 1.6.2  -td
+
+The vertical position of staff lines and the number of staff lines
+can be defined at the same time.  As the following example shows,
+note positions are not influenced by the staff line positions.
+
+@warning{The @code{'line-positions} property overrides the
+@code{'line-count} property.  The number of staff lines is
+implicitly defined by the number of elements in the list of values
+for @code{'line-positions}.}
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'line-positions = #'(7 3 0 -4 -6 -7)
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+The width of a staff can be modified.  The units are staff
+spaces.  The spacing of objects inside the staff is not affected by
+this setting.
+
+@lilypond[verbatim,quote,relative=1]
+\new Staff \with {
+  \override StaffSymbol #'width = #23
+}
+{ a4 e' f b | d1 }
+@end lilypond
+
+
 @node Spanners
 @subsection Spanners
 
@@ -2038,8 +2274,8 @@ the @code{\override} command is quite simple:
 
 @lilypond[relative=2,quote,verbatim]
 e2 \glissando b
-\once \override Glissando #'bound-details #'left #'Y = #3
-\once \override Glissando #'bound-details #'right #'Y = #-2
+\once \override Glissando #'(bound-details left Y) = #3
+\once \override Glissando #'(bound-details right Y) = #-2
 e2 \glissando b
 @end lilypond
 
@@ -2058,7 +2294,7 @@ sub-lists of @code{bound-details}.  For example:
 
 @lilypond[relative=2,ragged-right,verbatim,fragment]
 \override Glissando #'breakable = ##t
-\override Glissando #'bound-details #'right-broken #'Y = #-3
+\override Glissando #'(bound-details right-broken Y) = #-3
 c1 \glissando \break
 f1
 @end lilypond
@@ -2098,7 +2334,7 @@ This is a markup that is evaluated to yield the stencil.  It is used
 to put @i{cresc.}, @i{tr} and other text on horizontal spanners.
 
 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-\override TextSpanner #'bound-details #'left #'text
+\override TextSpanner #'(bound-details left text)
    = \markup { \small \bold Slower }
 c2\startTextSpan b c a\stopTextSpan
 @end lilypond
@@ -2112,15 +2348,15 @@ or @code{stencil-offset} will move the symbol at the edge vertically
 relative to the end point of the line:
 
 @lilypond[relative=1,fragment,verbatim]
-\override TextSpanner #'bound-details
-  #'left #'stencil-align-dir-y = #-2
-\override TextSpanner #'bound-details
-  #'right #'stencil-align-dir-y = #UP
-
-\override TextSpanner #'bound-details
-  #'left #'text = #"ggg"
-\override TextSpanner #'bound-details
-  #'right #'text = #"hhh"
+\override TextSpanner
+  #'(bound-details left stencil-align-dir-y) = #-2
+\override TextSpanner
+  #'(bound-details right stencil-align-dir-y) = #UP
+
+\override TextSpanner
+  #'(bound-details left text) = #"ggg"
+\override TextSpanner
+  #'(bound-details right text) = #"hhh"
 c4^\startTextSpan c c c \stopTextSpan
 @end lilypond
 
@@ -2159,9 +2395,7 @@ When using @code{\endSpanners} it is not necessary to close
 hairpins with @code{\!}.
 
 
-
 @seealso
-
 Internals Reference: @rinternals{TextSpanner},
 @rinternals{Glissando}, @rinternals{VoiceFollower},
 @rinternals{TrillSpanner},
@@ -2188,11 +2422,11 @@ certain layout objects.  These are covered under Special
 considerations.
 
 @menu
-* Removing the stencil::        
-* Making objects transparent::  
-* Painting objects white::      
-* Using break-visibility::      
-* Special considerations::      
+* Removing the stencil::
+* Making objects transparent::
+* Painting objects white::
+* Using break-visibility::
+* Special considerations::
 @end menu
 
 
@@ -2310,29 +2544,25 @@ object is printed at the end of, within the body of, or at the
 beginning of a line.  Or to be more precise, before a line break,
 where there is no line break, or after a line break.
 
-Alternatively, seven of the eight combinations may be specified
+Alternatively, these eight combinations may be specified
 by pre-defined functions, defined in @file{scm/output-lib.scm},
 where the last three columns indicate whether the layout objects
 will be visible in the positions shown at the head of the columns:
 
-@multitable @columnfractions .40 .15 .1 .1 .1
-@c TODO check these more carefully
+@multitable {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {yes} {yes} {yes}
 @headitem Function                   @tab Vector                  @tab Before @tab At no    @tab After
 @headitem form                       @tab form                    @tab break  @tab break    @tab break
 
-@item @code{all-invisible}           @tab @code{'#(#f #f #f)} @ @ @tab no     @tab no       @tab no
+@item @code{all-visible}             @tab @code{'#(#t #t #t)}     @tab yes    @tab yes      @tab yes
 @item @code{begin-of-line-visible}   @tab @code{'#(#f #f #t)}     @tab no     @tab no       @tab yes
+@item @code{center-visible}          @tab @code{'#(#f #t #f)}     @tab no     @tab yes      @tab no
 @item @code{end-of-line-visible}     @tab @code{'#(#t #f #f)}     @tab yes    @tab no       @tab no
-@item @code{all-visible}             @tab @code{'#(#t #t #t)}     @tab yes    @tab yes      @tab yes
-@c The center-visible function is not defined
-@c @item @code{center-visible}       @tab @code{'#(#f #t #f)}     @tab no     @tab yes      @tab no
 @item @code{begin-of-line-invisible} @tab @code{'#(#t #t #f)}     @tab yes    @tab yes      @tab no
-@item @code{end-of-line-invisible}   @tab @code{'#(#f #t #t)}     @tab no     @tab yes      @tab yes
 @item @code{center-invisible}        @tab @code{'#(#t #f #t)}     @tab yes    @tab no       @tab yes
+@item @code{end-of-line-invisible}   @tab @code{'#(#f #t #t)}     @tab no     @tab yes      @tab yes
+@item @code{all-invisible}           @tab @code{'#(#f #f #f)}     @tab no     @tab no       @tab no
 @end multitable
 
-The @code{center-visible} function is not pre-defined.
-
 The default settings of @code{break-visibility} depend on the
 layout object.  The following table shows all the layout objects
 of interest which are affected by @code{break-visibility} and the
@@ -2548,7 +2778,7 @@ override these:
 @c FIXME Complete
 @lilypond[relative=2,ragged-right,verbatim,fragment]
 e2 \glissando f
-\once \override Glissando #'bound-details #'right #'Y = #-2
+\once \override Glissando #'(bound-details right Y) = #-2
 e2 \glissando f
 @end lilypond
 
@@ -2637,8 +2867,8 @@ appearance of the printed score.
 * Modifying shapes::
 @end menu
 
-@seealso
 
+@seealso
 Learning Manual:
 @rlearning{Tweaking output},
 @rlearning{Other sources of information}.
@@ -2657,6 +2887,7 @@ Snippets:
 Internals Reference:
 @rinternals{All layout objects}.
 
+
 @node Aligning objects
 @subsection Aligning objects
 
@@ -2702,7 +2933,7 @@ marks on such objects.
 * Setting @code{X-offset} and @code{Y-offset} directly::
 * Using the @code{side-position-interface}::
 * Using the @code{self-alignment-interface}::
-* Using the @code{break-aligned-interface}::
+* Using the @code{break-alignable-interface}::
 @end menu
 
 @node Setting @code{X-offset} and @code{Y-offset} directly
@@ -2869,17 +3100,20 @@ example shows the difference:
 
 @c TODO The align-interface, BassFigureAlignment and VerticalAlignment
 
-@node Using the @code{break-aligned-interface}
-@unnumberedsubsubsec Using the @code{break-aligned-interface}
+@node Using the @code{break-alignable-interface}
+@unnumberedsubsubsec Using the @code{break-alignable-interface}
 
-Rehearsal marks may be aligned with notation objects other
-than bar lines.  These objects include @code{ambitus},
+@cindex align to objects
+@cindex break-align-symbols
+
+Rehearsal marks and bar numbers may be aligned with notation
+objects other than bar lines.  These objects include @code{ambitus},
 @code{breathing-sign}, @code{clef}, @code{custos}, @code{staff-bar},
 @code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
 @code{time-signature}.
 
-By default, rehearsal marks will be horizontally centered above the
-object:
+By default, rehearsal marks and bar numbers will be horizontally
+centered above the object:
 
 @lilypond[verbatim,quote,relative=1]
 e1
@@ -2898,6 +3132,32 @@ e
 e2.
 @end lilypond
 
+A list of possible target alignment objects may be specified.  If
+some of the objects are invisible at that point due to the setting
+of @code{break-visibility} or the explicit visibility settings for
+keys and clefs, the rehearsal mark or bar number is aligned to the
+first object in the list which is visible.  If no objects in the
+list are visible the object is aligned to the bar line.  If the bar
+line is invisible the object is aligned to the place where the bar
+line would be.
+
+@lilypond[verbatim,quote,relative=1]
+e1
+% the RehearsalMark will be centered above the Key Signature
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \major
+\clef treble
+\mark "↓"
+e
+% the RehearsalMark will be centered above the Clef
+\set Staff.explicitKeySignatureVisibility = #all-invisible
+\override Score.RehearsalMark #'break-align-symbols = #'(key-signature clef)
+\key a \minor
+\clef bass
+\mark "↓"
+e,
+@end lilypond
+
 The alignment of the rehearsal mark relative to the notation object
 can be changed, as shown in the following example.  In a score with
 multiple staves, this setting should be done for all the staves.
@@ -2942,7 +3202,6 @@ e
 @end lilypond
 
 
-
 @node Vertical grouping of grobs
 @subsection Vertical grouping of grobs
 
@@ -3003,8 +3262,8 @@ Any of the glyphs in the feta Font can be supplied to the
 
 @c TODO Add inserting Postscript or ref to later
 
-@seealso
 
+@seealso
 Notation Reference:
 @ref{Graphic notation inside markup},
 @ref{Formatting text},
@@ -3022,6 +3281,11 @@ Notation Reference:
 @node Modifying ties and slurs
 @unnumberedsubsubsec Modifying ties and slurs
 
+@cindex slurs, modifying
+@cindex ties, modifying
+@cindex Bézier curves
+@cindex Bézier control points
+
 Ties, slurs and phrasing slurs are drawn as third-order Bézier
 curves.  If the shape of the tie or slur which is calculated
 automatically is not optimum, the shape may be modified manually by
@@ -3070,13 +3334,16 @@ scaling can be achieved by applying the same transformation to the
 curve's control points.
 
 For the example above the following override gives a satisfactory
-tie:
+tie.  Note the placement -- it has to be immediately before the note
+to which the start of the tie (or slur) is attached.
 
 @lilypond[verbatim,quote,relative=1]
 <<
-  \once \override Tie
-    #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
-  { e1 ~ e1 }
+  {
+    \once \override Tie
+      #'control-points = #'((1 . -1) (3 . 0.6) (12.5 . 0.6) (14.5 . -1))
+     e1 ~ e1
+  }
 \\
   { r4 <g c,> <g c,> <g c,>4  }
 >>