]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/notation/changing-defaults.itely
Doc - NR + CG: Clarify Emmentaler is the 'font' and Feta/Parmesan are glyphs
[lilypond.git] / Documentation / notation / changing-defaults.itely
index 25771a986c71c972e4add0075931ba8b6856b142..7fad344bb6ee3cc4d281e36d49e55bbf77363115 100644 (file)
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.17.6"
+@c \version "2.19.22"
 
 @node Changing defaults
 @chapter Changing defaults
@@ -91,18 +91,12 @@ Internals Reference:
 
 >> > > - list of contexts: my *danger unmaintainable*
 >> > > alarm just went off.  I'm
-
 I knew it would... And leaving out some of them is perfectly fine
-with me.
-I do think that a list like this, with the main contexts and a
-brief
-description of  what they do (perhaps also with a note about what
-default
-behavior is associated with each of them, but this may be
-unmanageable),
-should be there, and then we could simply list the remaining ones
-without
-further explanation and with links to the IR.
+with me. I do think that a list like this, with the main contexts and a
+brief description of  what they do (perhaps also with a note about what
+default behavior is associated with each of them, but this may be
+unmanageable), should be there, and then we could simply list the
+remaining ones without further explanation and with links to the IR.
 @end ignore
 
 @c TODO Improve layout, order and consistency of wording -td
@@ -114,12 +108,57 @@ further explanation and with links to the IR.
 Contexts are arranged hierarchically:
 
 @menu
+* Output definitions - blueprints for contexts::
 * Score - the master of all contexts::
 * Top-level contexts - staff containers::
 * Intermediate-level contexts - staves::
 * Bottom-level contexts - voices::
 @end menu
 
+@node Output definitions - blueprints for contexts
+@unnumberedsubsubsec Output definitions - blueprints for contexts
+
+This section explains the relevance of output definitions when
+working with contexts.  Examples for actual output definitions are
+given later (see @ref{Changing all contexts of the same type}).
+
+@cindex output definitions
+@funindex \layout
+While music written in a file may refer to context types and
+names, contexts are created only when the music is actually being
+interpreted.  LilyPond interprets music under control of an
+@q{output definition} and may do so for several different output
+definitions, resulting in different output.  The output definition
+relevant for printing music is specified using @code{\layout}.
+
+@funindex \midi
+A much simpler output definition used for producing Midi output is
+specified using @code{\midi}.  Several other output definitions
+are used by LilyPond internally, like when using the part combiner
+(@ref{Automatic part combining}) or creating music quotes
+(@ref{Quoting other voices}).
+
+Output definitions define the relation between contexts as well as
+their respective default settings.  While most changes will
+usually be made inside of a @code{\layout} block, Midi-related
+settings will only have an effect when made within a @code{\midi}
+block.
+
+@funindex autoBeaming
+Some settings affect several outputs: for example, if
+@code{autoBeaming} is turned off in some context, beams count as
+melismata for the purpose of matching music to lyrics as described
+in @ref{Automatic syllable durations}.  This matching is done both
+for printed output as well as for Midi.  If changes made to
+@code{autoBeaming} within a context definition of a @code{\layout}
+block are not repeated in the corresponding @code{\midi} block,
+lyrics and music will get out of sync in Midi.
+
+@seealso
+Installed Files:
+@file{ly/engraver-init.ly}.
+@file{ly/performer-init.ly}.
+
 @node Score - the master of all contexts
 @unnumberedsubsubsec Score - the master of all contexts
 
@@ -130,8 +169,7 @@ such as clefs, time signatures, and key-signatures are aligned
 across staves.
 
 A Score context is instantiated implicitly when a
-@code{\score @{@dots{}@}} or @code{\layout @{@dots{}@}} block is
-processed.
+@code{\score @{@dots{}@}} block is processed.
 
 @node Top-level contexts - staff containers
 @unnumberedsubsubsec Top-level contexts - staff containers
@@ -169,8 +207,9 @@ Handles clefs, bar lines, keys, accidentals.  It can contain
 
 @strong{@emph{RhythmicStaff}}
 
-Like @code{Staff} but for printing rhythms.  Pitches are ignored;
-the notes are printed on one line.
+Like @code{Staff} but for printing rhythms.  Pitches are ignored
+when engraving; the notes are printed on one line.  The MIDI
+rendition retains pitches unchanged.
 
 @strong{@emph{TabStaff}}
 
@@ -179,7 +218,7 @@ expression out as a guitar tablature, printed on six lines.
 
 @strong{@emph{DrumStaff}}
 
-Handles typesetting for percussion.  Can contain @code{DrumVoice}
+Handles typesetting for percussion.  Can contain @code{DrumVoice}.
 
 @strong{@emph{VaticanaStaff}}
 
@@ -195,8 +234,10 @@ a piece in mensural style.
 @unnumberedsubsubsec Bottom-level contexts - voices
 
 Voice-level contexts initialise certain properties and start
-appropriate engravers.  Being bottom-level contexts, they cannot
-contain other contexts.
+appropriate engravers.  A bottom-level context is one without
+@code{defaultchild}.  While it is possible to let it
+accept/@/contain subcontexts, they can only be created and entered
+explicitly.
 
 @strong{@emph{Voice}}
 
@@ -300,14 +341,14 @@ context.
 The @code{\new} prefix without a name is commonly used to create
 scores with many staves:
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 <<
-  \new Staff {
+  \new Staff \relative {
     % leave the Voice context to be created implicitly
-    c4 c
+    c''4 c
   }
-  \new Staff {
-    d4 d
+  \new Staff \relative {
+    d''4 d
   }
 >>
 @end lilypond
@@ -315,18 +356,16 @@ scores with many staves:
 @noindent
 and to place several voices into one staff:
 
-@lilypond[quote,verbatim,relative=2]
-<<
-  \new Staff <<
-    \new Voice {
-      \voiceOne
-      c8 c c4 c c
-    }
-    \new Voice {
-      \voiceTwo
-      g4 g g g
-    }
-  >>
+@lilypond[quote,verbatim]
+\new Staff <<
+  \new Voice \relative {
+    \voiceOne
+    c''8 c c4 c c
+  }
+  \new Voice \relative {
+    \voiceTwo
+    g'4 g g g
+  }
 >>
 @end lilypond
 
@@ -341,18 +380,16 @@ action taken:
 @code{\new} with or without a name will always create a fresh,
 distinct, context, even if one with the same name already exists:
 
-@lilypond[quote,verbatim,relative=2]
-<<
-  \new Staff <<
-    \new Voice = "A" {
-      \voiceOne
-      c8 c c4 c c
-    }
-    \new Voice = "A" {
-      \voiceTwo
-      g4 g g g
-    }
-  >>
+@lilypond[quote,verbatim]
+\new Staff <<
+  \new Voice = "A" \relative {
+    \voiceOne
+    c''8 c c4 c c
+  }
+  \new Voice = "A" \relative {
+    \voiceTwo
+    g'4 g g g
+  }
 >>
 @end lilypond
 
@@ -381,13 +418,13 @@ from the musical content.  Either of these two forms is valid:
 
     % musical content
     \context Voice = "one" {
-      \relative c'' {
-        c4 c c c
+      \relative {
+        c''4 c c c
       }
     }
     \context Voice = "two" {
-      \relative c'' {
-        g8 g g4 g g
+      \relative {
+        g'8 g g4 g g
       }
     }
   >>
@@ -409,13 +446,13 @@ from the musical content.  Either of these two forms is valid:
 
     % musical content
     \context Voice = "one" {
-      \relative c'' {
-        c4 c c c
+      \relative {
+        c''4 c c c
       }
     }
     \context Voice = "two" {
-      \relative c'' {
-        g8 g g4 g g
+      \relative {
+        g'8 g g4 g g
       }
     }
   >>
@@ -427,7 +464,6 @@ Alternatively, variables may be employed to similar effect.  See
 @rlearning{Organizing pieces with variables}.
 
 @item
-
 @code{\context} with no name will match the first of any previously
 created contexts of the same type in the same context heirarchy,
 even one that has been given a name, and its music expression will be
@@ -437,8 +473,8 @@ is used to set the context in which a Scheme procedure specified with
 @code{\applyContext} is executed:
 
 @example
-\new Staff \relative c' @{
-  c1
+\new Staff \relative @{
+  c'1
   \context Timing
   \applyContext #(lambda (ctx)
                    (newline)
@@ -454,7 +490,7 @@ when lyrics are associated with music:
 
 @example
 \new Voice = "tenor" @var{music}
-...
+@dots{}
 \new Lyrics \lyricsto "tenor" @var{lyrics}
 @end example
 
@@ -470,7 +506,6 @@ musical content.  If a single context is to be modified, a @code{\with}
 block must be used, see @ref{Changing just one specific context}.
 
 @seealso
-
 Learning Manual:
 @rlearning{Organizing pieces with variables}.
 
@@ -487,22 +522,27 @@ Notation Reference:
 
 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.
+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.
+There is an exception to this general rule: inside of an
+@code{@{@dots{}@}} construct (sequential music), the construct's
+notion of the ``current context'' will descend whenever an element
+of the sequence ends in a subcontext of the previous current
+context.  This avoids spurious creation of implicit contexts in a
+number of situations but means that the first context descended
+into will be kept alive until the end of the expression.
+
+In contrast, the contexts of a @code{<<@dots{}>>} construct's
+(simultaneous music) expression are not carried forth, so
+enclosing a context creating command in an extra pair of
+@code{<<@dots{}>>} will keep the context from persisting through
+all of the enclosing @code{@{@dots{}@}} sequence.
 
 Any context can be kept alive by ensuring it has something to do at
 every musical moment.  @code{Staff} contexts are kept alive by
@@ -517,8 +557,8 @@ 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 }
+musicA = \relative { d''4 d d d }
+musicB = \relative { g'4 g g g }
 keepVoicesAlive = {
   <<
     \new Voice = "A" { s1*5 }  % Keep Voice "A" alive for 5 bars
@@ -556,8 +596,8 @@ 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 }
+melody = \relative { a'4 a a a }
+accompaniment = \relative { d'4 d d d }
 words = \lyricmode { These words fol -- low the mel -- o -- dy }
 \score {
   <<
@@ -595,14 +635,14 @@ 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'' {
+melody = \relative {
   s1  % skip a bar
-  a4 a a a
+  a'4 a a a
   s1  % skip a bar
   a4 a a a
 }
-accompaniment = \relative c' {
-  d4 d d d
+accompaniment = \relative {
+  d'4 d d d
   d4 d d d
   d4 d d d
   d4 d d d
@@ -673,7 +713,7 @@ modifying it,
   @emph{etc.}
 @}
 @{
-  @emph{..music..}
+  @emph{@dots{}music@dots{}}
 @}
 @end example
 
@@ -682,16 +722,16 @@ where the @dots{} should be the name of an engraver.  Here is a simple
 example which removes @code{Time_signature_engraver} and
 @code{Clef_engraver} from a @code{Staff} context,
 
-@lilypond[quote,relative=1,verbatim]
+@lilypond[quote,verbatim]
 <<
-  \new Staff {
-    f2 g
+  \new Staff \relative {
+    f'2 g
   }
   \new Staff \with {
      \remove "Time_signature_engraver"
      \remove "Clef_engraver"
-  } {
-    f2 g2
+  } \relative {
+    f'2 g2
   }
 >>
 @end lilypond
@@ -711,7 +751,7 @@ within the measure, etc.  By moving these engraver from @code{Score} to
 time signature.
 
 @cindex polymetric scores
-@cindex Time signatures, multiple
+@cindex time signature, multiple
 
 @lilypond[quote,verbatim]
 \score {
@@ -719,16 +759,18 @@ time signature.
     \new Staff \with {
       \consists "Timing_translator"
       \consists "Default_bar_line_engraver"
-    } {
+    }
+    \relative {
         \time 3/4
-        c4 c c c c c
+        c''4 c c c c c
     }
   \new Staff \with {
     \consists "Timing_translator"
     \consists "Default_bar_line_engraver"
-  } {
+  }
+  \relative {
       \time 2/4
-      c4 c c c c c
+      c''4 c c c c c
   }
 >>
 \layout {
@@ -802,9 +844,15 @@ default values in just one particular instance of a context.
 @funindex \context
 @funindex \layout
 
-The context settings which are to be used by default in
+The default context settings which are to be used for typesetting in
 @code{Score}, @code{Staff}, @code{Voice} and other contexts may be
-specified in a @code{\context} block within any @code{\layout} block.
+specified in a @code{\context} block within any @code{\layout}
+block.
+
+Settings for Midi output as opposed to typesetting will have to be
+separately specified in @code{\midi} blocks (see @ref{Output
+definitions - blueprints for contexts}).
+
 The @code{\layout} block should be placed within the @code{\score}
 block to which it is to apply, after the music.
 
@@ -829,8 +877,8 @@ An @code{\override} command, but with the context name omitted
 
 @lilypond[quote,verbatim]
 \score {
-  \relative c'' {
-    a4^"Thicker stems" a a a
+  \relative {
+    a'4^"Thicker stems" a a a
     a4 a a\ff a
   }
   \layout {
@@ -847,8 +895,8 @@ Directly setting a context property
 
 @lilypond[quote,verbatim]
 \score {
-  \relative c'' {
-    a4^"Smaller font" a a a
+  \relative {
+    a'4^"Smaller font" a a a
     a4 a a\ff a
   }
   \layout {
@@ -866,8 +914,8 @@ expression like @code{\accidentalStyle dodecaphonic}
 
 @lilypond[quote,verbatim]
 \score {
-  \relative c'' {
-    a4^"Dynamics above" a a a
+  \relative {
+    a'4^"Dynamics above" a a a
     a4 a a\ff a
   }
   \layout {
@@ -895,8 +943,8 @@ StaffDefaults = \with {
 
 \score {
   \new Staff {
-    \relative c'' {
-      a4^"Smaller font" a a a
+    \relative {
+      a'4^"Smaller font" a a a
       a4 a a a
     }
   }
@@ -923,8 +971,8 @@ the same command written in the music stream.
 @lilypond[quote,verbatim]
 \score {
   \new Staff {
-    \relative c'' {
-      a4^"Smaller font" a a a
+    \relative {
+      a'4^"Smaller font" a a a
       a4 a a a
     }
   }
@@ -951,14 +999,34 @@ must be placed immediately after the @code{\new} @var{context-type}
 command:
 
 @example
-\new Staff
-\with @{
-  [context settings for this context instance only]
-@} @{
-...
+\new Staff \with @{ [context settings for this context instance only] @}
+@{
+  @dots{}
+@}
+@end example
+
+Alternatively, if the music is being entered using the short form of the
+input mode-specifying commands, e.g. @code{\chords} rather than
+@code{\chordmode}, the @code{\with} command must be placed immediately
+after the mode-specifying command:
+
+@example
+\chords \with @{ [context settings for this (implicit) context instance only] @}
+@{
+  @dots{}
 @}
 @end example
 
+@noindent
+as it is the implicit context created by these short forms which should
+be modified.  The same consideration applies to the other input
+mode-specifying short forms (@code{\drums}, @code{\figures}), see
+@ref{Input modes}.
+
+Since context modifications specified in @code{\with} blocks are inside
+music, they will affect @emph{all} outputs (typesetting @emph{and}
+Midi) as opposed to changes within an output definition.
+
 The following types of settings may be specified:
 
 @itemize
@@ -968,13 +1036,10 @@ An @code{\override} command, but with the context name omitted
 @lilypond[quote,verbatim]
 \score {
   \new Staff {
-    \new Voice
-    \with {
-      \override Stem.thickness = #4.0
-    }
+    \new Voice \with { \override Stem.thickness = #4.0 }
     {
-      \relative c'' {
-        a4^"Thick stems" a a a
+      \relative {
+        a'4^"Thick stems" a a a
         a4 a a a
       }
     }
@@ -989,17 +1054,15 @@ Directly setting a context property
 \score {
   <<
     \new Staff {
-      \relative c'' {
-        a4^"Default font" a a a
+      \relative {
+        a'4^"Default font" a a a
         a4 a a a
       }
     }
-    \new Staff
-    \with {
-      fontSize = #-4
-    } {
-      \relative c'' {
-        a4^"Smaller font" a a a
+    \new Staff \with { fontSize = #-4 }
+    {
+      \relative {
+        a'4^"Smaller font" a a a
         a4 a a a
       }
     }
@@ -1015,20 +1078,18 @@ A predefined command such as @code{\dynamicUp}
   <<
     \new Staff {
       \new Voice {
-        \relative c'' {
-          a4^"Dynamics below" a a a
+        \relative {
+          a'4^"Dynamics below" a a a
           a4 a a\ff a
         }
       }
     }
-    \new Staff
-    \with { \accidentalStyle dodecaphonic }
+    \new Staff \with { \accidentalStyle dodecaphonic }
     {
-      \new Voice
-      \with { \dynamicUp }
+      \new Voice \with { \dynamicUp }
       {
-        \relative c'' {
-          a4^"Dynamics above" a a a
+        \relative {
+          a'4^"Dynamics above" a a a
           a4 a a\ff a
         }
       }
@@ -1039,6 +1100,10 @@ A predefined command such as @code{\dynamicUp}
 
 @end itemize
 
+@seealso
+Notation Reference:
+@ref{Input modes}
+
 @node Order of precedence
 @unnumberedsubsubsec Order of precedence
 
@@ -1056,7 +1121,8 @@ on the context initiation statement is used,
 
 @item
 otherwise the default value taken from the most recent appropriate
-@code{\context} block in the @code{\layout} blocks is used,
+@code{\context} block in the @code{\layout} or @code{\midi} blocks
+is used,
 
 @item
 otherwise the LilyPond built-in default is used.
@@ -1071,7 +1137,7 @@ Notation Reference:
 @ref{Bottom-level contexts - voices},
 @ref{The set command},
 @ref{The override command},
-@ref{The \layout block}.
+@ref{The layout block,,The @code{@bs{}layout} block}.
 
 
 @node Defining new contexts
@@ -1081,19 +1147,13 @@ Notation Reference:
 @cindex engravers, including in contexts
 
 @funindex \alias
-@funindex alias
 @funindex \name
-@funindex name
 @funindex \type
-@funindex type
 @funindex \consists
-@funindex consists
 @funindex \accepts
-@funindex accepts
 @funindex \denies
-@funindex denies
 
-Specific contexts, like @code{Staff} and @code{Voice}, are made of
+Specific contexts, like @code{Staff} and @code{Voice}, are made from
 simple building blocks.  It is possible to create new types of
 contexts with different combinations of engraver plug-ins.
 
@@ -1112,16 +1172,15 @@ to indicate improvisation in jazz pieces,
   \consists "Pitch_squash_engraver"
   squashedPosition = #0
   \override NoteHead.style = #'slash
-  \override Stem.transparent = ##t
-  \override Flag.transparent = ##t
+  \hide Stem
   \alias Voice
 }
 \context { \Staff
   \accepts "ImproVoice"
 }}
 
-\relative c'' {
-  a4 d8 bes8 \new ImproVoice { c4^"ad lib" c
+\relative {
+  a'4 d8 bes8 \new ImproVoice { c4^"ad lib" c
    c4 c^"undress" c_"while playing :)" c }
   a1
 }
@@ -1148,45 +1207,53 @@ First it is necessary to define a name for the new context:
 \name ImproVoice
 @end example
 
-Since it is similar to the @code{Voice}, we want commands that work
-on (existing) @code{Voice}s to remain working.  This is achieved by
-giving the new context an alias @code{Voice},
+Since it is similar to the @code{Voice} context, we want commands that
+work in (existing) @code{Voice} contexts to continue working.  This is
+achieved by giving the new context an alias of @code{Voice},
 
 @example
 \alias Voice
 @end example
 
 The context will print notes and instructive texts, so we need to add
-the engravers which provide this functionality,
+the engravers which provide this functionality, plus the engraver which
+groups notes, stems and rests which occur at the same musical moment
+into columns,
 
 @example
 \consists "Note_heads_engraver"
 \consists "Text_engraver"
+\consists "Rhythmic_column_engraver"
 @end example
 
-but we only need this on the center line,
+The note heads should all be placed on the center line,
 
 @example
 \consists "Pitch_squash_engraver"
 squashedPosition = #0
 @end example
 
-The @rinternals{Pitch_squash_engraver} modifies note heads (created
-by @rinternals{Note_heads_engraver}) and sets their vertical
-position to the value of @code{squashedPosition}, in this case@tie{}@code{0},
-the center line.
+The @code{Pitch_squash_engraver} modifies note heads (created
+by the @code{Note_heads_engraver}) and sets their vertical
+position to the value of @code{squashedPosition}, in this
+case@tie{}@code{0}, the center line.
 
 The notes look like a slash, and have no stem,
 
 @example
 \override NoteHead.style = #'slash
-\override Stem.transparent = ##t
-\override Flag.transparent = ##t
+\hide Stem
 @end example
 
-All these plug-ins have to cooperate, and this is achieved with a
-special plug-in, which must be marked with the keyword @code{\type}.
-This should always be @code{Engraver_group}.
+All these plug-ins have to communicate under the control of the
+context.  The mechanisms with which contexts communicate are
+established by declaring the context @code{\type}.  Within a
+@code{\layout} block, most contexts will be of type
+@code{Engraver_group}.  Some special contexts and contexts in
+@code{\midi} blocks use other context types.  Copying and
+modifying an existing context definition will also fill in the
+type.  Since this example creates a definition from scratch, it
+needs to be specified explicitly.
 
 @example
 \type "Engraver_group"
@@ -1200,20 +1267,20 @@ Put together, we get
   \type "Engraver_group"
   \consists "Note_heads_engraver"
   \consists "Text_engraver"
+  \consists "Rhythmic_column_engraver"
   \consists "Pitch_squash_engraver"
   squashedPosition = #0
   \override NoteHead.style = #'slash
-  \override Stem.transparent = ##t
-  \override Flag.transparent = ##t
+  \hide Stem
   \alias Voice
 @}
 @end example
 
 @funindex \accepts
-Contexts form hierarchies.  We want to hang the @code{ImproVoice}
-under @code{Staff}, just like normal @code{Voice}s.  Therefore, we
-modify the @code{Staff} definition with the @code{\accepts}
-command,
+Contexts form hierarchies.  We want to place the @code{ImproVoice}
+context within the @code{Staff} context, just like normal @code{Voice}
+contexts.  Therefore, we modify the @code{Staff} definition with the
+@code{\accepts} command,
 
 @example
 \context @{
@@ -1222,11 +1289,39 @@ command,
 @}
 @end example
 
+@funindex \inherit-acceptability
+Often when reusing an existing context definition, the resulting
+context can be used anywhere where the original context would have
+been useful.
+
+@example
+\layout @{
+  @dots{}
+  \inherit-acceptability @var{to} @var{from}
+@}
+@end example
+
+@noindent
+will arrange to have contexts of type @var{to} accepted by all
+contexts also accepting @var{from}.  For example, using
+
+@example
+\layout @{
+  @dots{}
+  \inherit-acceptability "ImproVoice" "Voice"
+@}
+@end example
+
+@noindent
+will add an @code{\accepts} for @code{ImproVoice} to both
+@code{Staff} and @code{RhythmicStaff} definitions.
+
 @funindex \denies
 The opposite of @code{\accepts} is @code{\denies},
 which is sometimes needed when reusing existing context definitions.
 
-Putting both into a @code{\layout} block, like
+Arranging the required pieces into a @code{\layout} block leaves
+us with
 
 @example
 \layout @{
@@ -1234,18 +1329,15 @@ Putting both into a @code{\layout} block, like
     \name ImproVoice
     @dots{}
   @}
-  \context @{
-    \Staff
-    \accepts "ImproVoice"
-  @}
+  \inherit-acceptability "ImproVoice" "Voice"
 @}
 @end example
 
 Then the output at the start of this subsection can be entered as
 
 @example
-\relative c'' @{
-  a4 d8 bes8
+\relative @{
+  a'4 d8 bes8
   \new ImproVoice @{
     c4^"ad lib" c
     c4 c^"undress"
@@ -1255,6 +1347,18 @@ Then the output at the start of this subsection can be entered as
 @}
 @end example
 
+To complete this example, changes affecting the context hierarchy
+should be repeated in a @code{\midi} block so that Midi output
+depends on the same context relations.
+
+@seealso
+
+Internals Reference:
+@rinternals{Note_heads_engraver},
+@rinternals{Text_engraver},
+@rinternals{Rhythmic_column_engraver},
+@rinternals{Pitch_squash_engraver}.
+
 
 @node Context layout order
 @subsection Context layout order
@@ -1273,33 +1377,42 @@ list will be repositioned below the outer context rather than nested
 within it.
 
 The @qq{accepts} list of a context can be changed with the
-@code{\accepts} and @code{\denies} commands.  @code{\accepts} adds a
+@code{\accepts} or @code{\denies} commands.  @code{\accepts} adds a
 context to the @qq{accepts} list and @code{\denies} removes a context
-from the list.  For example, it would not normally be desirable for
-chord names to be nested within a @code{Staff} context, so the
-@code{ChordNames} context is not included by default in the @qq{accepts}
-list of the @code{Staff} context, but if this were to be required it can
-be done:
+from the list.
+
+For example, a square-braced staff group is not usually found within a
+curved-braced staff with connecting staff bars, and a @code{GrandStaff}
+does not accept a @code{StaffGroup} inside it by default.
 
 @lilypond[verbatim,quote]
 \score {
-  \new Staff {
-    c' d' e' f'
-    \chords { d1:m7 b1:min7.5- }
-  }
+  \new GrandStaff <<
+    \new StaffGroup <<
+      \new Staff { c'1 }
+      \new Staff { d'1 }
+    >>
+    \new Staff { \set Staff.instrumentName = bottom f'1 }
+  >>
 }
 @end lilypond
 
+However, by using the @code{\accepts} command, @code{StaffGroup} can be
+added to the @code{GrandStaff} context:
+
 @lilypond[verbatim,quote]
 \score {
-  \new Staff {
-    c' d' e' f'
-    \chords { d1:m7 b1:min7.5- }
-  }
+  \new GrandStaff <<
+    \new StaffGroup <<
+      \new Staff { c'1 }
+      \new Staff { d'1 }
+    >>
+    \new Staff { \set Staff.instrumentName = bottom f'1 }
+  >>
   \layout {
     \context {
-      \Staff
-      \accepts "ChordNames"
+      \GrandStaff
+      \accepts "StaffGroup"
     }
   }
 }
@@ -1311,9 +1424,23 @@ another, but the required nesting differs.  For example, the
 with the @code{VaticanaVoice} context substituted for the @code{Voice}
 context in the @qq{accepts} list.
 
-Note that a context will be silently created implicitly if a command
-is encountered when there is no suitable context available to
-contain it.  This can give rise to unexpected new staves or scores.
+@cindex contexts, implicit
+@cindex implicit contexts
+@funindex \defaultchild
+
+Note that a context will be silently created implicitly if a
+command is encountered when there is no suitable context available
+to contain it.
+
+Within a context definition, the type of subcontext to be
+implicitly created is specified using @code{\defaultchild}.  A
+number of music events require a @samp{Bottom} context: when such
+an event is encountered, subcontexts are created recursively until
+reaching a context with no @samp{defaultchild} setting.
+
+Implicit context creation can at times give rise to unexpected new
+staves or scores.  Using @code{\new} to create contexts explicitly
+avoids those problems.
 
 @cindex alignAboveContext
 @cindex alignBelowContext
@@ -1329,7 +1456,7 @@ existing contexts.  To reposition it above the context called
 @qq{main}, it should be defined like this:
 
 @example
-@code{\new Staff \with @{ alignAboveContext = #"main" @} }
+\new Staff \with @{ alignAboveContext = #"main" @}
 @end example
 
 A similar situation arises when positioning a temporary lyrics
@@ -1378,10 +1505,8 @@ Installed Files:
 Suppose we want to move the fingering indication in the fragment
 below:
 
-@lilypond[quote,relative=2,verbatim]
-c-2
-\stemUp
-f
+@lilypond[quote,fragment,verbatim]
+c''-2
 @end lilypond
 
 If you visit the documentation on fingering instructions (in
@@ -1596,10 +1721,8 @@ is directly generated from this definition.
 
 Recall that we wanted to change the position of the @b{2} in
 
-@lilypond[quote,relative=2,verbatim]
-c-2
-\stemUp
-f
+@lilypond[quote,fragment,verbatim]
+c''-2
 @end lilypond
 
 Since the @b{2} is vertically positioned next to its note, we have to
@@ -1628,28 +1751,24 @@ Add this much extra space between objects that are next to each other.
 @end table
 @end quotation
 
-By increasing the value of @code{padding}, we can move the
-fingering away from the note head.  The following command inserts
-3 staff spaces of white
-between the note and the fingering:
+By increasing the value of @code{padding}, we can move the fingering
+away from the note head.  The following command will insert @qq{three
+staff spaces} worth of distance between the note and a fingering mark:
+
 @example
 \once \override Voice.Fingering.padding = #3
 @end example
 
-Inserting this command before the Fingering object is created,
-i.e., before @code{c2}, yields the following result:
+Inserting the padding before the fingering object is created results in
+the following:
 
-@lilypond[quote,relative=2,verbatim]
+@lilypond[quote,fragment,verbatim]
 \once \override Voice.Fingering.padding = #3
-c-2
-\stemUp
-f
+c''-2
 @end lilypond
 
-
-In this case, the context for this tweak is @code{Voice}.  This
-fact can also be deduced from the program reference, for the page for
-the @rinternals{Fingering_engraver} plug-in says
+In this case, the context for this tweak is @code{Voice}.  See
+@rinternals{Fingering_engraver} plug-in, which says:
 
 @quotation
 Fingering_engraver is part of contexts: @dots{} @rinternals{Voice}
@@ -1663,25 +1782,33 @@ Another thing that is needed, is an overview of the various naming
 conventions:
 
 @itemize
-@item scheme functions: lowercase-with-hyphens (incl. one-word
+@item scheme functions: lowercase-with-hyphens (also includes one-word
 names)
-@item scheme functions: ly:plus-scheme-style
+
+@item LilyPond-specific scheme functions: ly:plus-scheme-style
+
 @item music events, music classes and music properties:
 as-scheme-functions
+
 @item Grob interfaces: scheme-style
+
 @item backend properties: scheme-style (but X and Y!)
+
 @item contexts (and MusicExpressions and grobs): Capitalized or
 CamelCase
+
 @item context properties: lowercaseFollowedByCamelCase
-@item engravers:
-Capitalized_followed_by_lowercase_and_with_underscores
+
+@item engravers: Capitalized_followed_by_lowercase_and_with_underscores
 @end itemize
 
 Questions to be answered:
 @itemize
+
 @item Which of these are conventions and which are rules?
+
 @item Which are rules of the underlying language, and which are
-LP-specific?
+LilyPond-specific?
 @end itemize
 
 @node Modifying properties
@@ -1698,6 +1825,7 @@ LP-specific?
 * The override command::
 * The tweak command::
 * set versus override::
+* The offset command::
 * Modifying alists::
 @end menu
 
@@ -1747,12 +1875,12 @@ unit).  Since the command specifies @code{Staff} as context, it only
 applies to the current staff.  Other staves will keep their normal
 appearance.  Here we see the command in action:
 
-@lilypond[quote,verbatim,relative=2]
-c4
+@lilypond[quote,fragment,verbatim]
+c''4
 \override Staff.Stem.thickness = #4.0
-c4
-c4
-c4
+c''4
+c''4
+c''4
 @end lilypond
 
 The @code{\override} command changes the definition of the @code{Stem}
@@ -1763,11 +1891,11 @@ Analogous to @code{\set}, the @var{context} argument may be left out,
 causing the default context @code{Voice} to be used.  Adding
 @code{\once} applies the change during one timestep only.
 
-@lilypond[quote,verbatim,relative=2]
-c4
+@lilypond[quote,fragment,verbatim]
+c''4
 \once \override Stem.thickness = #4.0
-c4
-c4
+c''4
+c''4
 @end lilypond
 
 The @code{\override} must be done before the object is
@@ -1775,11 +1903,11 @@ started.  Therefore, when altering @emph{Spanner} objects such as slurs
 or beams, the @code{\override} command must be executed at the moment
 when the object is created.  In this example,
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
 \override Slur.thickness = #3.0
-c8[( c
+c''8[( c''
 \override Beam.beam-thickness = #0.6
-c8 c])
+c''8 c''])
 @end lilypond
 
 @noindent
@@ -1847,7 +1975,7 @@ the @code{#}@tie{}character.
 
 Contexts properties are usually named in
 @code{studlyCaps}.  They mostly control the translation from
-music to notation, e.g. @code{localKeySignature} (for determining
+music to notation, e.g., @code{localAlterations} (for determining
 whether to print accidentals), or @code{measurePosition} (for
 determining when to print a bar line).  Context properties can
 change value over time while interpreting a piece of music;
@@ -1857,7 +1985,7 @@ this.  Context properties are modified with @code{\set}.
 For example, multimeasure rests will be combined into a single bar
 if the context property @code{skipBars} is set to @code{#t}:
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
 R1*2
 \set Score.skipBars = ##t
 R1*2
@@ -1867,17 +1995,16 @@ If the @var{context} argument is left out, then the property will be
 set in the current bottom context (typically @code{ChordNames},
 @code{Voice}, @code{TabVoice}, or @code{Lyrics}).
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
 \set Score.autoBeaming = ##f
-<<
-  {
-    e8 e e e
-    \set autoBeaming = ##t
-    e8 e e e
-  } \\ {
-    c8 c c c c8 c c c
-  }
->>
+\relative {
+  e''8 e e e
+  \set autoBeaming = ##t
+  e8 e e e
+} \\
+\relative {
+  c''8 c c c c8 c c c
+}
 @end lilypond
 
 The change is applied @q{on-the-fly}, during the music, so that the
@@ -1889,7 +2016,7 @@ that you wish to change -- for example, attempting to set the
 @code{Voice}, will have no effect, because skipBars is a property of
 the @code{Score} context.
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
 R1*2
 \set skipBars = ##t
 R1*2
@@ -1914,18 +2041,17 @@ the definition only if it is set in @var{context}.
 Properties that have been set in enclosing contexts will
 not be altered by an unset in an enclosed context:
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
 \set Score.autoBeaming = ##t
-<<
-  {
-    \unset autoBeaming
-    e8 e e e
-    \unset Score.autoBeaming
-    e8 e e e
-  } \\ {
-    c8 c c c c8 c c c
-  }
->>
+\relative {
+  \unset autoBeaming
+  e''8 e e e
+  \unset Score.autoBeaming
+  e8 e e e
+} \\
+\relative {
+  c''8 c c c c8 c c c
+}
 @end lilypond
 
 Like @code{\set}, the @var{context} argument does not have to be
@@ -1941,14 +2067,14 @@ are equivalent if the current bottom context is @code{Voice}.
 
 
 @cindex \once
-Preceding a @code{\set} command by @code{\once} makes the
-setting apply to only a single time-step:
+Preceding a @code{\set} or @code{\unset} command by @code{\once}
+makes the setting apply to only a single time-step:
 
-@lilypond[quote,verbatim,relative=2]
-c4
+@lilypond[quote,fragment,verbatim]
+c''4
 \once \set fontSize = #4.7
-c4
-c4
+c''4
+c''4
 @end lilypond
 
 A full description of all available context properties is in the
@@ -1990,27 +2116,27 @@ For example, we can increase the thickness of a note stem by
 overriding the @code{thickness} property of the @code{Stem}
 object:
 
-@lilypond[quote,verbatim,relative=2]
-c4 c
+@lilypond[quote,fragment,verbatim]
+c''4 c''
 \override Voice.Stem.thickness = #3.0
-c4 c
+c''4 c''
 @end lilypond
 
 If no context is specified in an @code{\override}, the bottom
 context is used:
 
-@lilypond[quote,verbatim,relative=2]
-\override Staff.Stem.thickness = #3.0
-  <<
-    {
-      e4 e
-      \override Stem.thickness = #0.5
-      e4 e
-    } \\ {
-      c4 c c c
-    }
-  >>
-}
+@lilypond[quote,fragment,verbatim]
+\override Staff.Stem.thickness = #3.0
+<<
+  \relative {
+    e''4 e
+    \override Stem.thickness = #0.5
+    e4 e
+  } \\
+  \relative {
+    c''4 c c c
+  }
+>>
 @end lilypond
 
 Some tweakable options are called @q{subproperties} and reside inside
@@ -2041,52 +2167,52 @@ The syntax for the @code{\revert} command is
 
 For example,
 
-@lilypond[quote,verbatim,relative=2]
-c4
-\override Voice.Stem.thickness = #3.0
-c4 c
-\revert Voice.Stem.thickness
-c4
+@lilypond[quote,verbatim]
+\relative {
+  c''4
+  \override Voice.Stem.thickness = #3.0
+  c4 c
+  \revert Voice.Stem.thickness
+  c4
+}
 @end lilypond
 
 The effects of @code{\override} and @code{\revert} apply to all
 grobs in the affected context from the current time forward:
 
-@lilypond[quote,verbatim,relative=2]
-{
-  <<
-    {
-      e4
-      \override Staff.Stem.thickness = #3.0
-      e4 e e
-    } \\ {
-      c4 c c
-      \revert Staff.Stem.thickness
-      c4
-    }
-  >>
-}
+@lilypond[quote,verbatim]
+<<
+  \relative {
+    e''4
+    \override Staff.Stem.thickness = #3.0
+    e4 e e
+  } \\
+  \relative {
+    c''4 c c
+    \revert Staff.Stem.thickness
+    c4
+  }
+>>
 @end lilypond
 
 @funindex \once
 @cindex overriding for only one moment
 
-@code{\once} can be used with @code{\override}
+@code{\once} can be used with @code{\override} or @code{\revert}
 to affect only the current time step:
 
-@lilypond[quote,verbatim,relative=2]
-{
-  <<
-    {
-      \override Stem.thickness = #3.0
-      e4 e e e
-    } \\ {
-      c4
-      \once \override Stem.thickness = #3.0
-      c4 c c
-    }
-  >>
-}
+@lilypond[quote,verbatim]
+<<
+  \relative c {
+    \override Stem.thickness = #3.0
+    e''4 e e e
+  } \\
+  \relative {
+    c''4
+    \once \override Stem.thickness = #3.0
+    c4 c c
+  }
+>>
 @end lilypond
 
 
@@ -2156,16 +2282,18 @@ graphical objects.  For objects that are created directly from
 an item in the input file, you can use the @code{\tweak} command.
 For example:
 
-@lilypond[relative=2,verbatim,quote]
-< c
-  \tweak color #red
-  d
-  g
-  \tweak duration-log #1
-  a
-> 4
--\tweak padding #8
--^
+@lilypond[verbatim,quote]
+\relative {
+  < c''
+    \tweak color #red
+    d
+    g
+    \tweak duration-log #1
+    a
+  > 4
+  -\tweak padding #8
+  -^
+}
 @end lilypond
 
 
@@ -2191,15 +2319,15 @@ note, and able to modify it.
 
 So, this works:
 
-@lilypond[relative=2,verbatim,quote]
-<\tweak color #red c>4
+@lilypond[verbatim,fragment,quote]
+<\tweak color #red c''>4
 @end lilypond
 
 @noindent
 but this does not:
 
-@lilypond[relative=2,verbatim,quote]
-\tweak color #red c4
+@lilypond[verbatim,fragment,quote]
+\tweak color #red c''4
 @end lilypond
 
 @end ignore
@@ -2228,20 +2356,20 @@ include the following:
 In this example, the color of one note head and the type of another
 note head are modified within a single chord:
 
-@lilypond[relative=2,verbatim,quote]
-< c
+@lilypond[verbatim,fragment,quote]
+< c''
   \tweak color #red
-  d
-  g
+  d''
+  g''
   \tweak duration-log #1
-  a
+  a''
 > 4
 @end lilypond
 
 @code{\tweak} can be used to modify slurs:
 
-@lilypond[verbatim,quote,relative=1]
-c-\tweak thickness #5 ( d e f)
+@lilypond[verbatim,quote]
+\relative { c'-\tweak thickness #5 ( d e f) }
 @end lilypond
 
 
@@ -2252,10 +2380,10 @@ Tweaking a whole chord does not do anything since its music event
 only acts as a container, and all layout objects are created from events
 inside of the @code{EventChord}:
 
-@lilypond[relative=2,verbatim,quote]
-\tweak color #red c4
-\tweak color #red <c e>4
-<\tweak color #red c e>4
+@lilypond[verbatim,fragment,quote]
+\tweak color #red c''4
+\tweak color #red <c'' e''>4
+<\tweak color #red c'' e''>4
 @end lilypond
 
 The simple @code{\tweak} command cannot be used to modify any object
@@ -2269,10 +2397,10 @@ Such indirectly created layout objects can be tweaked using the form
 of the @code{\tweak} command in which the grob name is specified
 explicitly:
 
-@lilypond[relative=2,verbatim,quote]
+@lilypond[fragment,verbatim,quote]
 \tweak Stem.color #red
-\tweak Beam.color #green c8 e
-<c e \tweak Accidental.font-size #-3 ges>4
+\tweak Beam.color #green c''8 e''
+<c'' e'' \tweak Accidental.font-size #-3 ges''>4
 @end lilypond
 
 @code{\tweak} cannot be used to modify clefs or time
@@ -2283,14 +2411,14 @@ insertion of extra elements required to specify the context.
 Several @code{\tweak} commands may be placed before a
 notational element -- all affect it:
 
-@lilypond[verbatim,quote,relative=1]
-c
--\tweak style #'dashed-line
--\tweak dash-fraction #0.2
--\tweak thickness #3
--\tweak color #red
- \glissando
-f'
+@lilypond[verbatim,fragment,quote]
+c'
+  -\tweak style #'dashed-line
+  -\tweak dash-fraction #0.2
+  -\tweak thickness #3
+  -\tweak color #red
 \glissando
+f''
 @end lilypond
 
 The music stream which is generated from a section of an input file,
@@ -2319,19 +2447,373 @@ one encountered in the input file.
 @node set versus override
 @subsection @code{\set} vs. @code{\override}
 
-@c TODO -- This section is probably unnecessary now.
+@c TODO Should't a bunch of that be explained earlier?
 
-@ignore
-We have seen two methods of changing properties: @code{\set} and
-@code{\override}.  There are actually two different kinds of
-properties.
+@funindex \set
+@funindex \override
+
+The @code{\set} and @code{\override} commands manipulate properties
+associated with contexts.  In both cases, the properties follow a
+@emph{hierarchy of contexts}; properties that are not set themselves in
+a context will still show the values of their respective parent's
+context.
+
+The lifetime and value of a context property is dynamic and only
+available when music is being interpreted (i.e., @q{iterated}).  At the
+time of the context's creation, properties are initialized from its
+corresponding definitions (along with any other modifications) of that
+context.  Any subsequent changes are achieved with any
+@q{property-setting} commands that are within the music itself.
+
+Graphical Object (or @qq{grob}) definitions are a @emph{special}
+category of context properties as their structure and use is different
+from that of normal context properties.  Unlike normal context
+properties, grob definitions are subdivided into @emph{grob properties}.
+
+Also, in contrast to normal context properties, grob definitions have
+their own internal @q{bookkeeping} used to keep track of their own
+individual grob properties and any sub-properties.  This means that it
+is possible to define those parts within different contexts and yet
+still have the overall grob definition at the time of grob creation from
+all the pieces provided amongst the current context and its parent(s).
+
+A grob is usually created by an engraver at the time of interpreting a
+music expression and receives its initial properties from the current
+grob definition of the engraver's context.  The engraver (or other
+@q{backend} parts of LilyPond) can then change (or add to) the grob's
+initial properties.  However, this does not affect the context's own
+grob definition.
+
+What LilyPond calls @emph{grob properties} in the context of
+@q{user-level} tweaks are really the properties of a @emph{context's}
+own grob definition.
+
+Grob definitions are accessed with a different set of commands and are
+manipulated using @code{\override} and @code{\revert} and have a name
+starting with a capital letter (e.g., @samp{NoteHead}); whereas normal
+context properties are manipulated using @code{\set} and @code{\unset}
+and are named starting with a lowercase letter.
+
+@cindex tweak, relation to @code{\override}
+@funindex \tweak
+@funindex \overrideProperty
 
-@code{fontSize} is a special property: it is equivalent to
-entering @code{\override ... #'font-size} for all pertinent
-objects.  Since this is a common change, the special
-property (modified with @code{\set}) was created.
+The commands @code{\tweak} and @code{\overrideProperty} change grob
+properties by bypassing all context properties completely and, instead,
+catch grobs as they are being created, setting properties on them for
+a music event (@code{\tweak}) or, in the case of
+@code{\overrideProperty} for a specific override.
 
-@end ignore
+
+@node The offset command
+@subsection The @code{\offset} command
+
+@funindex \offset
+@cindex offsetting
+@cindex defaults, offsetting
+
+While it is possible to set grob properties to new values with the
+@code{\override}, @code{\tweak}, and @code{\overrideProperty} commands,
+it is often more convenient to modify such properties relative to a
+default value.  The @code{\offset} command is available for this
+purpose.
+
+The syntax for @code{\offset} is
+
+@example
+[-]\offset @var{property} @var{offsets} @var{item}
+@end example
+
+The command works by adding the contents of @var{offsets} to the
+default setting of the property @var{property} of the grob indicated by
+@var{item}.
+
+Depending on the formulation of the command, @code{\offset} may act
+as either a @code{\tweak} or @code{\override}.  The variations in
+usage are discussed after consideration is given to grob properties
+that may be used with @code{\offset}.
+
+@subsubsubheading{Properties which may be offset}
+
+Many, but not all, grob properties may be offset.  If @var{property}
+cannot be offset, the object will remain unchanged and a warning will
+be issued.  In such cases, @code{\override} or @code{\tweak} should be
+used to modify the object instead.
+
+One can work by trial and error and let the warnings be the guide to
+what may or may not be offset.  A more systematic approach is possible,
+however.
+
+The following criteria determine whether a property can be modified with
+@code{\offset}:
+
+@itemize
+
+@item
+The property has a @q{default setting} in the grob's description.  Such
+properties are listed for each grob in @rinternals{All layout objects}.
+(They are also found in @file{scm/define-grobs.scm}.)
+
+@item
+The property takes a numerical value.  Numerical values include
+@code{number}, list of @code{number}s, @code{number-pair}, and
+@code{number-pair-list}.  The pages at @rinternals{All layout objects}
+list the type of data characteristic to each property.  It is immaterial
+whether the default setting is a function.
+
+@item
+The property cannot be a @q{subproperty}---a property residing within
+another property.
+
+@item
+Properties set to infinite values cannot be offset.  There is no
+sensible way to offset positive and negative infinity.
+@end itemize
+
+The following examples consider several grob properties against the
+criteria outlined above.
+
+@itemize
+
+@item Properties that may be offset
+
+@table @asis
+
+@item @code{Hairpin.height}
+
+This property is not a subproperty, and it is listed at
+@rinternals{Hairpin}.  For a value, it takes @q{dimension, in staff
+space} set to @code{0.6666}---clearly a non-infinite @code{number}.
+
+@item @code{Arpeggio.positions}
+
+The page @rinternals{Arpeggio} lists a @code{positions} property which
+accepts a @q{pair of numbers}.  It defaults to
+@code{ly:arpeggio::positions}---a callback which will be evaluated
+during the typesetting phase to yield a pair of numbers for any given
+@code{Arpeggio} object.
+
+@end table
+
+@item Properties that may not be offset
+
+@table @asis
+
+@item @code{Hairpin.color}
+
+There is no listing for @code{color} at @rinternals{Hairpin}.
+
+@item @code{Hairpin.circled-tip}
+
+The listing for @code{Hairpin.circled-tip} at @rinternals{Hairpin} shows
+that it takes a @code{boolean} value.  Booleans are non-numerical.
+
+@item @code{Stem.details.lengths}
+
+Though listed at @rinternals{Stem} and defaulting to a list of
+@code{number}s, this is a @q{subproperty}.  There is currently no
+support for @q{nested properties}.
+
+@end table
+
+@end itemize
+
+@subsubsubheading{@bs{}offset as an override}
+
+If @var{item} is a grob name like @code{Arpeggio} or
+@code{Staff.OttavaBracket}, the result is an @code{\override} of the
+specified grob-type.
+
+@example
+\offset @var{property} @var{offsets} [@var{context}.]@var{GrobName}
+@end example
+
+Note that the leading hyphen is @emph{never} used with the @q{override}
+form, just as it is never used with the @code{\override} command itself.
+
+The following example uses the @q{override} form to lengthen the
+default arpeggios shown in the first measure to cover the extent of
+the chords more fully.  The arpeggios are stretched by a half
+staff-space to top and bottom.  Also shown is the same operation done on
+the first chord with an ordinary override of the @code{positions}
+property.  This method is not at all expressive of the task of
+@q{stretching by a half staff-space}, as the endpoints must be specified
+with absolute rather than relative coordinates.  Furthermore, individual
+overrides would be needed for the other chords, as they vary in size and
+position.
+
+@lilypond[quote,verbatim]
+arpeggioMusic = {
+  <c' e' g'>\arpeggio <a' c'' e''>\arpeggio
+  <d' f' a' c''>\arpeggio <c' e' g' b' d'' f'' a''>\arpeggio
+}
+
+{
+  \arpeggioMusic
+  \bar "||"
+  \offset positions #'(-0.5 . 0.5) Arpeggio
+  \arpeggioMusic
+  \bar "||"
+  \once \override Arpeggio.positions = #'(-3.5 . -0.5)
+  <c' e' g'>1\arpeggio
+  \bar "||"
+}
+@end lilypond
+
+In its @q{override} usage, @code{\offset} may be prefaced with
+@code{\once} or @code{\temporary} and reverted using @code{\revert} with
+@var{property}.  This follows from the fact that @code{\offset} actually
+creates an @code{\override} of @var{property}.
+
+@lilypond[quote,verbatim]
+music = { c'8\< d' e' f'\! }
+
+{
+  \music
+  \offset height 1 Hairpin
+  \music
+  \music
+  \revert Hairpin.height
+  \music
+  \bar "||"
+  \once \offset height 1 Hairpin
+  \music \music
+  \bar "||"
+  \override Hairpin.height = 0.2
+  \music
+  \temporary \offset height 2 Hairpin
+  \music
+  \music
+  \revert Hairpin.height
+  \music
+  \bar "||"
+}
+@end lilypond
+
+Also like @code{\override}, the @q{override} form of @code{\offset} may
+be used with @code{\undo} and @code{\single}.
+
+@lilypond[quote,verbatim]
+longStem = \offset length 6 Stem
+
+{
+ \longStem c'4 c''' c' c''
+ \bar "||"
+ \undo \longStem c'4 c''' c' c''
+ \bar "||"
+ \single \longStem c'4 c''' c' c''
+ \bar "||"
+}
+@end lilypond
+
+@subsubsubheading{@bs{}offset as a tweak}
+
+If @var{item} is a music expression such as @code{(} or
+@code{\arpeggio}, the result is the same music expression with a tweak
+applied.
+
+@example
+[-]\offset [@var{GrobName}.]@var{property} @var{offsets} @var{music-expression}
+@end example
+
+The syntax of @code{\offset} in its @q{tweak} form is analogous to the
+@code{\tweak} command itself, both in ordering and in the presence or
+absence of the leading hyphen.
+
+The following example uses the @q{tweak} form to adjust the vertical
+position of the @code{BreathingSign} object.  Compare this with the
+ordinary @code{\tweak} command also demonstrated.  The syntax is
+equivalent; however, the output of @code{\tweak} is less intuitive,
+since @code{BreathingSign.Y-offset} is calculated from the middle
+staff-line.  It is not necessary to know how @code{Y-offset} is
+calculated when using @code{\offset}.
+
+@lilypond[quote,verbatim]
+{
+  c''4
+  \breathe
+  c''4
+  \offset Y-offset 2 \breathe
+  c''2
+  \tweak Y-offset 3 \breathe
+}
+@end lilypond
+
+In the previous example, the tweaked objects were created directly from
+the user input: the @code{\breathe} command was an explicit instruction
+to return a @code{BreathingSign} object.  Since the focus of the command
+was unambiguous, there was no need to specify the object's name.  When
+an object is @emph{indirectly} created, however, it is necessary to
+include the grob's name.  This is the same as for the @code{\tweak}
+command.
+
+In the following example, the @code{Beam} object is lowered two
+staff-spaces by applying @code{\offset} to the @code{positions}
+property.
+
+The first application of @code{\offset} requires that the grob's name
+be included, because nothing in the input explicitly creates the
+beam.  In the second application, the beam is created manually with the
+music expression @code{[}; therefore, the grob's name is not needed.
+(Also illustrated is a shorthand: a single @code{number} will be applied
+to both members of a @code{number-pair}.)
+
+@lilypond[quote,verbatim]
+{
+  c''8 g'' e'' d''
+  \offset Beam.positions #'(-2 . -2)
+  c''8 g'' e'' d''
+  c''8 g'' e'' d''
+  c''8-\offset positions #-2 [ g'' e'' d'']
+}
+@end lilypond
+
+@subsubsubheading{@bs{}offset with broken spanners}
+
+Independently modifying segments of a spanner extending over a line
+break or breaks is also possible.  In this case, @var{offsets}
+takes a list of values of the property's required data type.
+
+The @code{\offset} command used in this manner is similar to the
+@code{\alterBroken} command.  (See @ref{Modifying broken spanners}.)
+In contrast with @code{\alterBroken}, however, the values given to
+@code{\offset} are relative, not absolute.
+
+The following example displaces the @q{broken} @code{OttavaBracket}
+object through its @code{staff-padding} property.  Since the property
+takes a @code{number}, @var{offsets} is provided with a list of
+@code{number}s to account for the two segments created by the line
+break.  The slur piece on the first line is effectively untouched since
+@code{0} is added to its default value.  The segment on the second
+line is raised two staff-spaces from its default height.  The default
+height happens to be @code{2}, though it is not necesssary to know this.
+
+@lilypond[quote,verbatim]
+{
+  \offset staff-padding #'(0 3) Staff.OttavaBracket
+  \ottava #1
+  c'''2 c'''
+  \break
+  c'''2 c'''
+}
+@end lilypond
+
+The following example mimics the effect of the @code{\shape} command by
+offsetting the @code{control-points} property of the @code{Slur} object.
+Here, @var{offsets} is a list of @code{number-pair-list}s, one for each
+slur segment.  This example achieves a result identical to the
+corresponding illustration at @ref{Modifying shapes}.
+
+@lilypond[quote,verbatim]
+{
+  c'4-\offset control-points #'(
+               ((0 . 0) (0 . 0) (0 . 0) (0 . 1))
+               ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
+              ) ( f'4 g' c''
+  \break
+  d'4 c'' f' c')
+}
+@end lilypond
 
 
 @node Modifying alists
@@ -2441,7 +2923,7 @@ values.  Unless this is the intended result, it is safer to update
 key-values individually with a nested declaration.
 
 @warning{Nested declarations will not work for context property
-alists (such as @code{beamExceptions}, @code{keySignature},
+alists (such as @code{beamExceptions}, @code{keyAlterations},
 @code{timeSignatureSettings}, etc.).  These properties can only be
 modified by completely re-defining them as alists.}
 
@@ -2454,6 +2936,7 @@ modified by completely re-defining them as alists.}
 * Input modes::
 * Direction and placement::
 * Distances and measurements::
+* Dimensions::
 * Staff symbol properties::
 * Spanners::
 * Visibility of objects::
@@ -2465,45 +2948,58 @@ modified by completely re-defining them as alists.}
 @subsection Input modes
 
 The way in which the notation contained within an input file is
-interpreted is determined by the current input mode.
+interpreted is determined by the current input mode.  In general,
+there are two ways of specifying the mode: a long form, e.g.
+@code{\chordmode}, and a short form, e.g. @code{\chords}.  The long
+form is typically used when supplying input to a variable or when
+entering input directly into an explicitly created context.  The short
+form implicitly creates a context of the correct type for the input and
+passes the input directly to it.  It is useful in simple situations
+when there is no requirement to explicitly create the receiving context.
 
-@strong{Chord mode}
+@subsubsubheading Chord mode
 
 This is activated with the @code{\chordmode} command, and causes
 input to be interpreted with the syntax of chord notation, see
-@ref{Chord notation}.  Chords are rendered as notes on a staff.
+@ref{Chord notation}.  Music in chord mode is rendered as chords on a staff
+when entered into a @code{Staff} context, as chord names when entered
+into a @code{ChordNames} context or as fret boards when entered into
+a @code{FretBoards} context.
 
-Chord mode is also activated with the @code{\chords} command.
-This also creates a new @code{ChordNames} context and
-causes the following input to be interpreted with the syntax of
-chord notation and rendered as chord names in the @code{ChordNames}
-context, see @ref{Printing chord names}.
+Chord mode is also activated with the @code{\chords} command.  This
+also causes the following input to be interpreted with the syntax of
+chord notation but in addition it implicitly creates a new
+@code{ChordNames} context and renders the input into it as chord names,
+see @ref{Printing chord names}.
 
-@strong{Drum mode}
+@subsubsubheading Drum mode
 
 This is activated with the @code{\drummode} command, and causes
 input to be interpreted with the syntax of drum notation, see
-@ref{Basic percussion notation}.
+@ref{Basic percussion notation}.  Music in drum mode is rendered as
+percussion notes when entered into a @code{DrumStaff} context.
 
-Drum mode is also activated with the @code{\drums} command.
-This also creates a new @code{DrumStaff} context and causes the
-following input to be interpreted with the syntax of drum notation
-and rendered as drum symbols on a drum staff, see @ref{Basic
-percussion notation}.
+Drum mode is also activated with the @code{\drums} command.  This
+also causes the following input to be interpreted with the syntax of
+drum notation but in addition it implicitly creates a new
+@code{DrumStaff} context and renders the input into it as percussion
+notes, see @ref{Basic percussion notation}.
 
-@strong{Figure mode}
+@subsubsubheading Figure mode
 
 This is activated with the @code{\figuremode} command, and causes
 input to be interpreted with the syntax of figured bass, see
-@ref{Entering figured bass}.
+@ref{Entering figured bass}.  Music in figure mode is rendered as
+figured bass when entered into a @code{FiguredBass} context or a
+@code{Staff} context.
 
 Figure mode is also activated with the @code{\figures} command.
-This also creates a new @code{FiguredBass} context and causes the
-following input to be interpreted with the figured bass syntax
-and rendered as figured bass symbols in the @code{FiguredBass}
-context, see @ref{Introduction to figured bass}.
+This also causes the following input to be interpreted with the
+figured bass syntax but in addition it implicitly creates a new
+@code{FiguredBass} context and renders the input into it as figured
+bass, see @ref{Introduction to figured bass}.
 
-@strong{Fret and tab modes}
+@subsubsubheading Fret and tab modes
 
 There are no special input modes for entering fret and tab symbols.
 
@@ -2511,32 +3007,37 @@ To create tab diagrams, enter notes or chords in note mode and
 render them in a @code{TabStaff} context, see
 @ref{Default tablatures}.
 
-To create fret diagrams above a staff, you have two choices.
-You can either use the @code{FretBoards} context (see
-@ref{Automatic fret diagrams} or you can enter them as a markup
-above the notes using the @code{\fret-diagram} command (see
-@ref{Fret diagram markups}).
+To create fret diagrams above a staff, enter notes or chords in either
+note mode or chord mode and render them in a @code{FretBoards} context,
+see @ref{Automatic fret diagrams}.  Alternatively, fret diagrams can be
+entered as markup above the notes using the @code{\fret-diagram}
+command, see @ref{Fret diagram markups}.
 
-@strong{Lyrics mode}
+@subsubsubheading Lyrics mode
 
 This is activated with the @code{\lyricmode} command, and causes
 input to be interpreted as lyric syllables with optional durations
-and associated lyric modifiers, see @ref{Vocal music}.
+and associated lyric modifiers, see @ref{Vocal music}.  Input in
+lyric mode is rendered as lyric syllables when entered into a
+@code{Lyrics} context.
 
-Lyric mode is also activated with the @code{\addlyrics} command.
-This also creates a new @code{Lyrics} context and an implicit
-@code{\lyricsto} command which associates the following lyrics
-with the preceding music.
+Lyric mode is also activated with the @code{\lyrics} command.  This
+also causes the following input to be interpreted as lyric syllables
+but in addition it implicitly creates a new @code{Lyrics} context and
+renders the input into it as lyric syllables.
 
-@strong{Markup mode}
+Lyric mode is also activated with the @code{\addlyrics} command.  This
+also implicitly creates a new @code{Lyrics} context and in addition it
+adds an implicit @code{\lyricsto} command which associates the following
+lyrics with the preceding music, see @ref{Automatic syllable durations}.
+
+@subsubsubheading Markup mode
 
 This is activated with the @code{\markup} command, and causes
 input to be interpreted with the syntax of markup, see
 @ref{Text markup commands}.
 
-@c silly work-around for texinfo broken-ness
-@c (@strong{Note...} causes a spurious cross-reference in Info)
-@b{Note mode}
+@subsubsubheading Note mode
 
 This is the default mode or it may be activated with the
 @code{\notemode} command.  Input is interpreted as pitches,
@@ -2547,23 +3048,6 @@ it may be useful to do so in certain situations, for example if you
 are in lyric mode, chord mode or any other mode and want to insert
 something that only can be done with note mode syntax.
 
-For example, to indicate dynamic markings for the verses of a
-choral pieces it is necessary to enter note mode to interpret
-the markings:
-
-@lilypond[verbatim,relative=2,quote]
-{ c4 c4 c4 c4 }
-\addlyrics {
-  \notemode{\set stanza = \markup{ \dynamic f 1. } }
-  To be sung loudly
-}
-\addlyrics {
-  \notemode{\set stanza = \markup{ \dynamic p 2. } }
-  To be sung quietly
-}
-@end lilypond
-
-
 
 @node Direction and placement
 @subsection Direction and placement
@@ -2581,10 +3065,11 @@ be desirable to force a particular direction or placement.
 * The direction property::
 @end menu
 
+
 @node Articulation direction indicators
 @unnumberedsubsubsec Articulation direction indicators
 
-By default some directions are always up or always down (e.g.
+By default some directions are always up or always down (e.g.,
 dynamics or fermata), while other things can alternate between
 up or down based on the stem direction (like slurs or accents).
 
@@ -2601,20 +3086,23 @@ but a direction indicator is @strong{always} required before
 @item @code{\tweak} commands
 @item @code{\markup} commands
 @item @code{\tag} commands
-@item string markups, e.g. -"string"
-@item fingering instructions, e.g. @w{@code{-1}}
-@item articulation shortcuts, e.g. @w{@code{-.}}, @w{@code{->}}, @w{@code{--}}
+@item string markups, e.g., -"string"
+@item fingering instructions, e.g., @w{@code{-1}}
+@item articulation shortcuts, e.g., @w{@code{-.}}, @w{@code{->}}, @w{@code{--}}
 @end itemize
 
 Direction indicators affect only the next note:
 
-@lilypond[verbatim,quote,relative=2]
-c2( c)
-c2_( c)
-c2( c)
-c2^( c)
+@lilypond[verbatim,quote]
+\relative {
+  c''2( c)
+  c2_( c)
+  c2( c)
+  c2^( c)
+}
 @end lilypond
 
+
 @node The direction property
 @unnumberedsubsubsec The direction property
 
@@ -2630,7 +3118,7 @@ Alternatively, in many cases predefined commands exist to specify the
 direction.  These are of the form
 
 @example
-@code{\xxxUp}, @code{\xxxDown} or @code{\xxxNeutral}
+\xxxUp, \xxxDown or \xxxNeutral
 @end example
 
 @noindent
@@ -2654,18 +3142,20 @@ TrillPitchGroup - not tried
 
 These indications affect all notes until they are canceled.
 
-@lilypond[verbatim,quote,relative=2]
-c2( c)
-\slurDown
-c2( c)
-c2( c)
-\slurNeutral
-c2( c)
+@lilypond[verbatim,quote]
+\relative {
+  c''2( c)
+  \slurDown
+  c2( c)
+  c2( c)
+  \slurNeutral
+  c2( c)
+}
 @end lilypond
 
 In polyphonic music, it is generally better to specify an explicit
-@code{voice} than change an object's direction.  For more information.
-See @ref{Multiple voices}.
+@code{voice} than change an object's direction.  For more information,
+see @ref{Multiple voices}.
 
 @seealso
 Learning Manual:
@@ -2732,6 +3222,35 @@ Notation Reference:
 @ref{Setting the staff size}.
 
 
+@node Dimensions
+@subsection Dimensions
+
+@cindex dimensions
+@cindex bounding box
+
+The dimensions of a graphical object specify the positions of the left
+and right edges and the bottom and top edges of the objects' bounding
+box as distances from the objects' reference point in units of
+staff-spaces.  These positions are usually coded as two Scheme pairs.
+For example, the text markup command @code{\with-dimensions} takes
+three arguments, the first two of which are a Scheme pair giving the
+left and right edge positions and a Scheme pair giving the bottom and
+top edge positions:
+
+@example
+\with-dimensions #'(-5 . 10) #'(-3 . 15) @var{arg}
+@end example
+
+This specifies a bounding box for @var{arg} with its left edge at -5,
+its right edge at 10, its bottom edge at -3 and its top edge at 15,
+all measured from the objects' reference point in units of
+staff-spaces.
+
+@seealso
+Notation Reference:
+@ref{Distances and measurements}.
+
+
 @node Staff symbol properties
 @subsection Staff symbol properties
 
@@ -2753,22 +3272,22 @@ note positions are not influenced by the staff line positions.
 implicitly defined by the number of elements in the list of values
 for @code{'line-positions}.}
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
 \new Staff \with {
   \override StaffSymbol.line-positions = #'(7 3 0 -4 -6 -7)
 }
-{ a4 e' f b | d1 }
+\relative { 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]
+@lilypond[verbatim,quote]
 \new Staff \with {
   \override StaffSymbol.width = #23
 }
-{ a4 e' f b | d1 }
+\relative { a4 e' f b | d1 }
 @end lilypond
 
 
@@ -2826,44 +3345,49 @@ Works not at all for:
 
 @end ignore
 
-@lilypond[verbatim,quote,relative=2]
-a~a
-a
+@lilypond[verbatim,quote,fragment]
+a'~ a'
+a'
 % increase the length of the tie
 -\tweak minimum-length #5
-~a
+~ a'
 @end lilypond
 
-@lilypond[verbatim,quote,relative=2]
-a1
-\compressFullBarRests
-R1*23
-% increase the length of the rest bar
-\once \override MultiMeasureRest.minimum-length = #20
-R1*23
-a1
+@lilypond[verbatim,quote]
+\relative \compressMMRests {
+  a'1
+  R1*23
+  % increase the length of the rest bar
+  \once \override MultiMeasureRest.minimum-length = #20
+  R1*23
+  a1
+}
 @end lilypond
 
-@lilypond[verbatim,quote,relative=2]
-a \< a a a \!
-% increase the length of the hairpin
-\override Hairpin.minimum-length = #20
-a \< a a a \!
+@lilypond[verbatim,quote]
+\relative {
+  a' \< a a a \!
+  % increase the length of the hairpin
+  \override Hairpin.minimum-length = #20
+  a \< a a a \!
+}
 @end lilypond
 
 This override can also be used to increase the length of slurs and
 phrasing slurs:
 
-@lilypond[verbatim,quote,relative=2]
-a( a)
-a
--\tweak minimum-length #5
-( a)
+@lilypond[verbatim,quote]
+\relative {
+  a'( g)
+  a
+  -\tweak minimum-length #5
+  ( g)
 
-a\( a\)
-a
--\tweak minimum-length #5
-\( a\)
+  a\( g\)
+  a
+  -\tweak minimum-length #5
+  \( g\)
+}
 @end lilypond
 
 For some layout objects, the @code{minimum-length} property becomes
@@ -2873,31 +3397,31 @@ be set to @code{ly:spanner::set-spacing-rods}.  For example,
 the minimum length of a glissando has no effect unless the
 @code{springs-and-rods} property is set:
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,fragment,quote]
 % default
-e \glissando c'
+e' \glissando c''
 
 % not effective alone
 \once \override Glissando.minimum-length = #20
-e, \glissando c'
+e' \glissando c''
 
 % effective only when both overrides are present
 \once \override Glissando.minimum-length = #20
 \once \override Glissando.springs-and-rods = #ly:spanner::set-spacing-rods
-e, \glissando c'
+e' \glissando c''
 @end lilypond
 
 The same is true of the @code{Beam} object:
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,fragment,quote]
 % not effective alone
 \once \override Beam.minimum-length = #20
-e8 e e e
+e'8 e' e' e'
 
 % effective only when both overrides are present
 \once \override Beam.minimum-length = #20
 \once \override Beam.springs-and-rods = #ly:spanner::set-spacing-rods
-e8 e e e
+e'8 e' e' e'
 @end lilypond
 
 @subsubsubheading The @code{to-barline} property
@@ -2909,10 +3433,12 @@ end instead on the immediately preceding bar line.  If set to false,
 the spanner will extend beyond the bar line and end on the note
 itself:
 
-@lilypond[verbatim,quote,relative=2]
-a \< a a a a \! a a a \break
-\override Hairpin.to-barline = ##f
-a \< a a a a \! a a a
+@lilypond[verbatim,quote]
+\relative {
+  a' \< a a a a \! a a a \break
+  \override Hairpin.to-barline = ##f
+  a \< a a a a \! a a a
+}
 @end lilypond
 
 This property is not effective for all spanners.  For example,
@@ -2934,7 +3460,7 @@ Objects which support the @code{line-spanner-interface} include
 @end itemize
 
 The routine responsible for drawing the stencils for these spanners is
-@code{ly:line-interface::print}.  This routine determines the
+@code{ly:line-spanner::print}.  This routine determines the
 exact location of the two end points and draws a line
 between them, in the style requested.  The locations of the two
 end points of the spanner are computed on-the-fly, but it is
@@ -2943,11 +3469,11 @@ properties which need to be specified are nested
 two levels down within the property hierarchy, but the syntax of
 the @code{\override} command is quite simple:
 
-@lilypond[relative=2,quote,verbatim]
-e2 \glissando b
+@lilypond[quote,fragment,verbatim]
+e''2 \glissando b'
 \once \override Glissando.bound-details.left.Y = #3
 \once \override Glissando.bound-details.right.Y = #-2
-e2 \glissando b
+e''2 \glissando b'
 @end lilypond
 
 The units for the @code{Y} property are @code{staff-space}s,
@@ -2963,11 +3489,11 @@ In case of a line break, the values for the end points are
 specified by the @code{left-broken} and @code{right-broken}
 sub-lists of @code{bound-details}.  For example:
 
-@lilypond[relative=2,ragged-right,verbatim,quote]
+@lilypond[ragged-right,fragment,verbatim,quote]
 \override Glissando.breakable = ##t
 \override Glissando.bound-details.right-broken.Y = #-3
-c1 \glissando \break
-f1
+c''1 \glissando \break
+f''1
 @end lilypond
 
 
@@ -3004,10 +3530,10 @@ recommended that @code{text} be used instead.
 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,relative=2,verbatim]
+@lilypond[quote,ragged-right,fragment,verbatim]
 \override TextSpanner.bound-details.left.text
    = \markup { \small \bold Slower }
-c2\startTextSpan b c a\stopTextSpan
+\relative { c''2\startTextSpan b c a\stopTextSpan }
 @end lilypond
 
 @item stencil-align-dir-y
@@ -3018,13 +3544,14 @@ end-point, centered on the line, as defined by the @code{X} and
 or @code{stencil-offset} will move the symbol at the edge vertically
 relative to the end point of the line:
 
-@lilypond[relative=1,quote,verbatim]
+@lilypond[quote,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"
-c4^\startTextSpan c c c \stopTextSpan
+
+\relative { c'4^\startTextSpan c c c \stopTextSpan }
 @end lilypond
 
 Note that negative values move the text @emph{up}, contrary to the
@@ -3035,7 +3562,7 @@ the top edge of the text with the spanner line.
 
 @item arrow
 Setting this sub-property to @code{#t} produces an arrowhead at the
-end of the line.
+end-points of the line.
 
 @item padding
 This sub-property controls the space between the specified
@@ -3050,11 +3577,13 @@ is terminated after exactly one note, or at the following bar line
 if @code{to-barline} is true and a bar line occurs before the next
 note.
 
-@lilypond[verbatim,quote,ragged-right,relative=2]
-\endSpanners
-c2 \startTextSpan c2 c2
-\endSpanners
-c2 \< c2 c2
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+  \endSpanners
+  c2 \startTextSpan c2 c2
+  \endSpanners
+  c2 \< c2 c2
+}
 @end lilypond
 
 When using @code{\endSpanners} it is not necessary to close
@@ -3102,6 +3631,7 @@ considerations.
 @unnumberedsubsubsec Removing the stencil
 
 @cindex stencil, removing
+@funindex \omit
 
 Every layout object has a stencil property.  By default this is set
 to the specific function which draws that object.  If this property
@@ -3109,7 +3639,7 @@ is overridden to @code{#f} no function will be called and the object
 will not be drawn.  The default action can be recovered with
 @code{\revert}.
 
-@lilypond[quote,verbatim,relative=1]
+@lilypond[quote,fragment,verbatim]
 a1 a
 \override Score.BarLine.stencil = ##f
 a a
@@ -3117,19 +3647,38 @@ a a
 a a a
 @end lilypond
 
+This rather common operation has a shortcut @code{\omit}:
+
+@lilypond[quote,fragment,verbatim]
+a1 a
+\omit Score.BarLine
+a a
+\undo \omit Score.BarLine
+a a a
+@end lilypond
+
 @node Making objects transparent
 @unnumberedsubsubsec Making objects transparent
 
 @cindex transparent, making objects
+@funindex \hide
 
 Every layout object has a transparent property which by default is
 set to @code{#f}.  If set to @code{#t} the object still occupies
 space but is made invisible.
 
-@lilypond[quote,verbatim,relative=2]
-a4 a
+@lilypond[quote,fragment,verbatim]
+a'4 a'
 \once \override NoteHead.transparent = ##t
-a a
+a' a'
+@end lilypond
+
+This rather common operation has a shortcut @code{\hide}:
+
+@lilypond[quote,fragment,verbatim]
+a'4 a'
+\once \hide NoteHead
+a' a'
 @end lilypond
 
 @node Painting objects white
@@ -3151,9 +3700,9 @@ points will be determined by the order in which they are drawn,
 and this may leave a ghostly image of the white object, as shown
 here:
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
 \override Staff.Clef.color = #white
-a1
+a'1
 @end lilypond
 
 This may be avoided by changing the order of printing the objects.
@@ -3172,10 +3721,10 @@ value of @code{1}, is drawn after the staff lines (default
 the @code{Clef} object must be given in a lower value of
 @code{layer}, say @w{@code{-1}}, so that it is drawn earlier:
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,fragment,verbatim]
 \override Staff.Clef.color = #white
 \override Staff.Clef.layer = #-1
-a1
+a'1
 @end lilypond
 
 @node Using break-visibility
@@ -3217,18 +3766,18 @@ 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 {@code{begin-of-line-invisible}} {@code{'#(#t #t #t)}} {Before} {At no} {After}
-@headitem Function                   @tab Vector                  @tab Before @tab At no    @tab After
-@headitem form                       @tab form                    @tab break  @tab break    @tab break
-
-@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{begin-of-line-invisible} @tab @code{'#(#t #t #f)}     @tab yes    @tab yes      @tab no
-@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
+@multitable {@code{begin-of-line-invisible}} {@code{#(#t #t #t)}} {Before} {At no} {After}
+@headitem Function                   @tab Vector                 @tab Before @tab At no    @tab After
+@headitem form                       @tab form                   @tab break  @tab break    @tab break
+
+@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{begin-of-line-invisible} @tab @code{#(#t #t #f)}     @tab yes    @tab yes      @tab no
+@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 default settings of @code{break-visibility} depend on the
@@ -3254,7 +3803,7 @@ default setting of this property:
 @item @code{KeySignature}        @tab @code{Staff}          @tab @code{begin-of-line-visible}
 @c omit LeftEdge until it can be explained -td
 @c @item @code{LeftEdge}         @tab @code{Score}          @tab @code{center-invisible}
-@item @code{OctavateEight}       @tab @code{Staff}          @tab @code{begin-of-line-visible}
+@item @code{ClefModifier}       @tab @code{Staff}          @tab @code{begin-of-line-visible}
 @item @code{RehearsalMark}       @tab @code{Score}          @tab @code{end-of-line-invisible}
 @item @code{TimeSignature}       @tab @code{Staff}          @tab @code{all-visible}
 
@@ -3263,14 +3812,16 @@ default setting of this property:
 The example below shows the use of the vector form to control the
 visibility of bar lines:
 
-@lilypond[quote,verbatim,relative=1,ragged-right]
-f4 g a b
-f4 g a b
-% Remove bar line at the end of the current line
-\once \override Score.BarLine.break-visibility = ##(#f #t #t)
-\break
-f4 g a b
-f4 g a b
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+  f'4 g a b
+  f4 g a b
+  % Remove bar line at the end of the current line
+  \once \override Score.BarLine.break-visibility = ##(#f #t #t)
+  \break
+  f4 g a b
+  f4 g a b
+}
 @end lilypond
 
 Although all three components of the vector used to override
@@ -3279,17 +3830,23 @@ effective with every layout object, and some combinations may
 even give errors.  The following limitations apply:
 
 @itemize @bullet
-@item Bar lines cannot be printed at start of line.
-@item A bar number cannot be printed at the start of the first
-line unless it is set to be different from 1.
-@item Clef -- see below
-@item Double percent repeats are either all printed or all
-suppressed.  Use begin-of line-invisible to print and
-all-invisible to suppress.
-@item Key signature -- see below
-@item OctavateEight -- see below
+@item Bar lines cannot be printed at the start of line.
+
+@item A bar number cannot be printed at the start of the @emph{first}
+line unless it is set to be different from @code{1}.
+
+@item Clef -- see the next section.
+
+@item Double percent repeats are either @emph{all printed} or
+@emph{all suppressed}.  Use @code{begin-of-line-invisible}
+to print them and @code{all-invisible} to suppress them.
+
+@item Key signature -- see the next section.
+
+@item ClefModifier -- see the next section.
 @end itemize
 
+
 @node Special considerations
 @unnumberedsubsubsec Special considerations
 
@@ -3302,23 +3859,25 @@ all-invisible to suppress.
 
 The @code{break-visibility} property controls the visibility of
 key signatures and changes of clef only at the start of lines,
-i.e. after a break.  It has no effect on the visibility of the
+i.e., after a break.  It has no effect on the visibility of the
 key signature or clef following an explicit key change or an
 explicit clef change within or at the end of a line.  In the
 following example the key signature following the explicit change
 to B-flat major is still visible, even though @code{all-invisible}
 is set.
 
-@lilypond[quote,verbatim,relative=1,ragged-right]
-\key g \major
-f4 g a b
-% Try to remove all key signatures
-\override Staff.KeySignature.break-visibility = #all-invisible
-\key bes \major
-f4 g a b
-\break
-f4 g a b
-f4 g a b
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+  \key g \major
+  f'4 g a b
+  % Try to remove all key signatures
+  \override Staff.KeySignature.break-visibility = #all-invisible
+  \key bes \major
+  f4 g a b
+  \break
+  f4 g a b
+  f4 g a b
+}
 @end lilypond
 
 The visibility of such explicit key signature and clef changes is
@@ -3335,15 +3894,17 @@ signatures and clefs at the beginning of lines;
 @code{break-visibility} must still be overridden in the appropriate
 object to remove these.
 
-@lilypond[quote,verbatim,relative=1,ragged-right]
-\key g \major
-f4 g a b
-\set Staff.explicitKeySignatureVisibility = #all-invisible
-\override Staff.KeySignature.break-visibility = #all-invisible
-\key bes \major
-f4 g a b \break
-f4 g a b
-f4 g a b
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+  \key g \major
+  f'4 g a b
+  \set Staff.explicitKeySignatureVisibility = #all-invisible
+  \override Staff.KeySignature.break-visibility = #all-invisible
+  \key bes \major
+  f4 g a b \break
+  f4 g a b
+  f4 g a b
+}
 @end lilypond
 
 @subsubsubheading Visibility of cancelling accidentals
@@ -3352,16 +3913,18 @@ To remove the cancelling accidentals printed at an explicit key
 change, set the Staff context property @code{printKeyCancellation}
 to @code{#f}:
 
-@lilypond[quote,verbatim,relative=1,ragged-right]
-\key g \major
-f4 g a b
-\set Staff.explicitKeySignatureVisibility = #all-invisible
-\set Staff.printKeyCancellation = ##f
-\override Staff.KeySignature.break-visibility = #all-invisible
-\key bes \major
-f4 g a b \break
-f4 g a b
-f4 g a b
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+  \key g \major
+  f'4 g a b
+  \set Staff.explicitKeySignatureVisibility = #all-invisible
+  \set Staff.printKeyCancellation = ##f
+  \override Staff.KeySignature.break-visibility = #all-invisible
+  \key bes \major
+  f4 g a b \break
+  f4 g a b
+  f4 g a b
+}
 @end lilypond
 
 With these overrides only the accidentals before the notes remain
@@ -3372,30 +3935,34 @@ the cancelling accidentals would be the @emph{only} indication of
 the key change.  In this case setting @code{printKeyCancellation} to
 @code{#f} has no effect:
 
-@lilypond[quote,verbatim,relative=1,ragged-right]
-\key g \major
-f4 g a b
-\set Staff.explicitKeySignatureVisibility = #all-invisible
-\set Staff.printKeyCancellation = ##f
-\key c \major
-f4 g a b \break
-f4 g a b
-f4 g a b
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+  \key g \major
+  f'4 g a b
+  \set Staff.explicitKeySignatureVisibility = #all-invisible
+  \set Staff.printKeyCancellation = ##f
+  \key c \major
+  f4 g a b \break
+  f4 g a b
+  f4 g a b
+}
 @end lilypond
 
 To suppress the cancelling accidentals even when the key is
 changed to C@tie{}major or A@tie{}minor, override
 the visibility of the @code{KeyCancellation} grob instead:
 
-@lilypond[quote,verbatim,relative=1,ragged-right]
-\key g \major
-f4 g a b
-\set Staff.explicitKeySignatureVisibility = #all-invisible
-\override Staff.KeyCancellation.break-visibility = #all-invisible
-\key c \major
-f4 g a b \break
-f4 g a b
-f4 g a b
+@lilypond[quote,verbatim,ragged-right]
+\relative {
+  \key g \major
+  f'4 g a b
+  \set Staff.explicitKeySignatureVisibility = #all-invisible
+  \override Staff.KeyCancellation.break-visibility = #all-invisible
+  \key c \major
+  f4 g a b \break
+  f4 g a b
+  f4 g a b
+}
 @end lilypond
 
 @c TODO Add visibility of cautionary accidentals before notes
@@ -3416,20 +3983,20 @@ occur only at explicit @code{\bar} commands.
 
 @c TODO Add example
 
-@subsubsubheading Octavated clefs
+@subsubsubheading Transposed clefs
 
-@cindex octavated clefs, visibility of
-@cindex visibility of octavated clefs
-@cindex clefs, visibility of octavation
+@cindex transposed clefs, visibility of
+@cindex visibility of transposed clefs
+@cindex clefs, visibility of transposition
 
-The small octavation symbol on octavated clefs is produced by the
-@code{OctavateEight} layout object.  Its visibility is automatically
+The small transposition symbol on transposed clefs is produced by the
+@code{ClefModifier} layout object.  Its visibility is automatically
 inherited from the @code{Clef} object, so it is not necessary to apply
-any required @code{break-visibility} overrides to the @code{OctavateEight} 
-layout objects to suppress octavation symbols for invisible clefs.
+any required @code{break-visibility} overrides to the @code{ClefModifier}
+layout objects to suppress transposition symbols for invisible clefs.
 
 For explicit clef changes, the @code{explicitClefVisibility}
-property controls both the clef symbol and any octavation symbol
+property controls both the clef symbol and any transposition symbol
 associated with it.
 
 @seealso
@@ -3448,23 +4015,25 @@ These all use the same routines as the glissando for drawing the
 texts and the lines, and tuning their behavior is therefore also
 done in the same way.  It is done with a spanner, and the routine
 responsible for drawing the spanners is
-@code{ly:line-interface::print}.  This routine determines the
+@code{ly:line-spanner::print}.  This routine determines the
 exact location of the two @i{span points} and draws a line
 between them, in the style requested.
 
 Here is an example showing the different line styles available,
 and how to tune them.
 
-@lilypond[relative=2,ragged-right,verbatim,quote]
-d2 \glissando d'2
-\once \override Glissando.style = #'dashed-line
-d,2 \glissando d'2
-\override Glissando.style = #'dotted-line
-d,2 \glissando d'2
-\override Glissando.style = #'zigzag
-d,2 \glissando d'2
-\override Glissando.style = #'trill
-d,2 \glissando d'2
+@lilypond[ragged-right,verbatim,quote]
+\relative {
+  d''2 \glissando d'2
+  \once \override Glissando.style = #'dashed-line
+  d,2 \glissando d'2
+  \override Glissando.style = #'dotted-line
+  d,2 \glissando d'2
+  \override Glissando.style = #'zigzag
+  d,2 \glissando d'2
+  \override Glissando.style = #'trill
+  d,2 \glissando d'2
+}
 @end lilypond
 
 The locations of the end-points of the spanner are computed
@@ -3472,10 +4041,12 @@ on-the-fly for every graphic object, but it is possible to
 override these:
 
 @c TODO Complete
-@lilypond[relative=2,ragged-right,verbatim,quote]
-e2 \glissando f
-\once \override Glissando.bound-details.right.Y = #-2
-e2 \glissando f
+@lilypond[ragged-right,verbatim,quote]
+\relative {
+  e''2 \glissando f
+  \once \override Glissando.bound-details.right.Y = #-2
+  e2 \glissando f
+}
 @end lilypond
 
 The value for @code{Y} is set to @w{@code{-2}} for the right end
@@ -3523,10 +4094,10 @@ There are only a few situations where the rotation of layout
 objects is useful; the following example shows one situation where
 they may be:
 
-@lilypond[quote,verbatim,relative=1]
-g4\< e' d' f\!
+@lilypond[quote,fragment,verbatim]
+g4\< e' d'' f''\!
 \override Hairpin.rotation = #'(20 -1 0)
-g,,4\< e' d' f\!
+g4\< e' d'' f''\!
 @end lilypond
 
 @node Rotating markup
@@ -3542,12 +4113,12 @@ rotated text.  In the following example the
 to disable the automatic collision avoidance, which would push some
 of the text too high.
 
-@lilypond[quote,verbatim,relative=1]
+@lilypond[quote,fragment,verbatim]
 \override TextScript.outside-staff-priority = ##f
 g4^\markup { \rotate #30 "a G" }
 b^\markup { \rotate #30 "a B" }
-des^\markup { \rotate #30 "a D-Flat" }
-fis^\markup { \rotate #30 "an F-Sharp" }
+des'^\markup { \rotate #30 "a D-Flat" }
+fis'^\markup { \rotate #30 "an F-Sharp" }
 @end lilypond
 
 @node Advanced tweaks
@@ -3561,6 +4132,7 @@ appearance of the printed score.
 * Vertical grouping of grobs::
 * Modifying stencils::
 * Modifying shapes::
+* Modifying broken spanners::
 * Unpure-pure containers::
 @end menu
 
@@ -3647,13 +4219,13 @@ properties of many objects.  The following example shows three
 notes with the default fingering position and the positions with @code{X-offset}
 and @code{Y-offset} modified.
 
-@lilypond[verbatim,quote,relative=2]
-a-3
-a
+@lilypond[verbatim,fragment,quote]
+a'-3
+a'
 -\tweak X-offset #0
 -\tweak Y-offset #0
 -3
-a
+a'
 -\tweak X-offset #-1
 -\tweak Y-offset #1
 -3
@@ -3728,7 +4300,7 @@ value of @code{self-alignment-X}, but the @code{\tweak} command
 can be used to separately align several annotations on a single
 note:
 
-@lilypond[quote,verbatim,relative=1]
+@lilypond[quote,verbatim,fragment]
 a'
 -\tweak self-alignment-X #-1
 ^"left-aligned"
@@ -3766,8 +4338,8 @@ be aligned in both directions simultaneously.
 The following example shows how to adjust a fingering mark so
 that it nestles close to the note head.
 
-@lilypond[quote,verbatim,relative=2]
-a
+@lilypond[quote,verbatim,fragment]
+a'
 -\tweak self-alignment-X #0.5  % move horizontally left
 -\tweak Y-offset #ly:self-alignment-interface::y-aligned-on-self
 -\tweak self-alignment-Y #-1  % move vertically up
@@ -3815,29 +4387,29 @@ objects other than bar lines.  These objects include @code{ambitus},
 @code{left-edge}, @code{key-cancellation}, @code{key-signature}, and
 @code{time-signature}.
 
-By default, rehearsal marks and bar numbers will be horizontally
-centered above the object:
+Each type of object has its own default reference point, to which
+rehearsal marks are aligned:
 
-@lilypond[verbatim,quote,relative=1]
-% The rehearsal mark will be centered above the Clef
+@lilypond[verbatim,quote,fragment]
+% The rehearsal mark will be aligned to the right edge of the Clef
 \override Score.RehearsalMark.break-align-symbols = #'(clef)
 \key a \major
 \clef treble
 \mark "↓"
-e1
-% The rehearsal mark will be centered above the Time Signature
+e'1
+% The rehearsal mark will be aligned to the left edge of the Time Signature
 \override Score.RehearsalMark.break-align-symbols = #'(time-signature)
 \key a \major
 \clef treble
 \time 3/4
 \mark "↓"
-e2.
+e'2.
 % The rehearsal mark will be centered above the Breath Mark
 \override Score.RehearsalMark.break-align-symbols = #'(breathing-sign)
 \key a \major
 \clef treble
 \time 4/4
-e1
+e'1
 \breathe
 \mark "↓"
 @end lilypond
@@ -3851,20 +4423,20 @@ 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]
-% The rehearsal mark will be centered above the Key Signature
+@lilypond[verbatim,quote,fragment]
+% The rehearsal mark will be aligned to the right edge of the Key Signature
 \override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
 \key a \major
 \clef treble
 \mark "↓"
-e1
-% The rehearsal mark will be centered above the Clef
+e'1
+% The rehearsal mark will be aligned to the right edge of the Clef
 \set Staff.explicitKeySignatureVisibility = #all-invisible
 \override Score.RehearsalMark.break-align-symbols = #'(key-signature clef)
 \key a \major
 \clef bass
 \mark "↓"
-gis,,1
+gis,1
 % The rehearsal mark will be centered above the Bar Line
 \set Staff.explicitKeySignatureVisibility = #all-invisible
 \set Staff.explicitClefVisibility = #all-invisible
@@ -3872,50 +4444,50 @@ gis,,1
 \key a \major
 \clef treble
 \mark "↓"
-e''1
+e'1
 @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.
 
-@lilypond[verbatim,quote,relative=1]
-% The RehearsalMark will be centered above the Key Signature
+@lilypond[verbatim,quote,fragment]
+% The RehearsalMark will be aligned with the right edge of the Key Signature
 \override Score.RehearsalMark.break-align-symbols = #'(key-signature)
 \key a \major
 \clef treble
 \time 4/4
 \mark "↓"
-e1
-% The RehearsalMark will be aligned with the left edge of the Key Signature
-\once \override Score.KeySignature.break-align-anchor-alignment = #LEFT
+e'1
+% The RehearsalMark will be centered above the Key Signature
+\once \override Score.KeySignature.break-align-anchor-alignment = #CENTER
 \mark "↓"
 \key a \major
-e1
-% The RehearsalMark will be aligned with the right edge of the Key Signature
-\once \override Score.KeySignature.break-align-anchor-alignment = #RIGHT
+e'1
+% The RehearsalMark will be aligned with the left edge of the Key Signature
+\once \override Score.KeySignature.break-align-anchor-alignment = #LEFT
 \key a \major
 \mark "↓"
-e1
+e'1
 @end lilypond
 
 The rehearsal mark can also be offset to the right or left of the left
 edge by an arbitrary amount.  The units are staff-spaces:
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote,fragment]
 % The RehearsalMark will be aligned with the left edge of the Key Signature
 % and then shifted right by 3.5 staff-spaces
 \override Score.RehearsalMark.break-align-symbols = #'(key-signature)
 \once \override Score.KeySignature.break-align-anchor = #3.5
 \key a \major
 \mark "↓"
-e1
+e'1
 % The RehearsalMark will be aligned with the left edge of the Key Signature
 % and then shifted left by 2 staff-spaces
 \once \override Score.KeySignature.break-align-anchor = #-2
 \key a \major
 \mark "↓"
-e1
+e'1
 @end lilypond
 
 
@@ -3928,7 +4500,7 @@ The VerticalAlignment and VerticalAxisGroup grobs work together.
 VerticalAxisGroup groups together different grobs like Staff, Lyrics,
 etc.  VerticalAlignment then vertically aligns the different grobs
 grouped together by VerticalAxisGroup.  There is usually only one
-VerticalAlignment per score but every Staff, Lyrics, etc. has its own
+VerticalAlignment per score but every Staff, Lyrics, etc., has its own
 VerticalAxisGroup.
 
 
@@ -3967,24 +4539,27 @@ XinO = {
       \musicglyph #"noteheads.s2cross"
   }
 }
-\relative c'' {
-  a a \XinO a a
+\relative {
+  a' a \XinO a a
 }
 @end lilypond
 
-Any of the glyphs in the feta Font can be supplied to the
-@code{\musicglyph} markup command -- see @ref{The Feta font}.
+Any of the @emph{Feta} glyphs used in the Emmentaler font can be
+supplied to the @code{\musicglyph} markup command -- see
+@ref{The Emmentaler font}.
 
-@c TODO Add inserting eps files or ref to later
+@file{EPS} files and Postscript commands can both be inserted inline
+using the @code{\epsfile} and @code{\postscript} markup commands
+respectively -- see @ref{Graphic}.
 
-@c TODO Add inserting Postscript or ref to later
 
 @seealso
 Notation Reference:
 @ref{Graphic notation inside markup},
 @ref{Formatting text},
 @ref{Text markup commands},
-@ref{The Feta font}.
+@ref{The Emmentaler font},
+@ref{Graphic}.
 
 
 @node Modifying shapes
@@ -4047,11 +4622,11 @@ the same operations on the curve.
 In this example the automatic placement of the tie is not optimum,
 and @code{\tieDown} would not help.
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
 <<
-  { e1~ e }
+  { e'1~ 1 }
 \\
-  { r4 <g c,> <g c,> <g c,> }
+  \relative { r4 <g' c,> <g c,> <g c,> }
 >>
 @end lilypond
 
@@ -4061,7 +4636,7 @@ the collisions to be avoided.
 The syntax of @code{\shape} is
 
 @example
-[-]@code{\shape} @var{displacements} @var{item}
+[-]\shape @var{displacements} @var{item}
 @end example
 
 This will reposition the control-points of @var{item} by the amounts
@@ -4087,14 +4662,14 @@ is being used.
 So, using the same example as above and the @code{\once\override}
 form of @code{\shape}, this will raise the tie by half a staff-space:
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
 <<
   {
     \shape #'((0 . 0.5) (0 . 0.5) (0 . 0.5) (0 . 0.5)) Tie
-    e1~ e
+    e'1~ 1
   }
 \\
-  { r4 <g c,> <g c,> <g c,> }
+  \relative { r4 <g' c,> <g c,> <g c,> }
 >>
 @end lilypond
 
@@ -4102,13 +4677,13 @@ This positioning of the tie is better, but maybe it should be raised
 more in the center.  The following example does this, this time using
 the alternative @code{\tweak} form:
 
-@lilypond[verbatim,quote,relative=1]
+@lilypond[verbatim,quote]
 <<
   {
-    e1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e
+    e'1-\shape #'((0 . 0.5) (0 . 1) (0 . 1) (0 . 0.5)) ~ e'
   }
 \\
-  { r4 <g c,> <g c,> <g c,> }
+  \relative { r4 <g' c,> <g c,> <g c,> }
 >>
 @end lilypond
 
@@ -4116,11 +4691,13 @@ Changes to the horizontal positions of the control points may be made
 in the same way, and two different curves starting at the same
 musical moment may also be shaped:
 
-@lilypond[verbatim,quote,ragged-right,relative=2]
-c8(\( a) a'4 e c\)
-\shape #'((0.7 . -0.4) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
-\shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
-c8(\( a) a'4 e c\)
+@lilypond[verbatim,quote,ragged-right]
+\relative {
+  c''8(\( a) a'4 e c\)
+  \shape #'((0.7 . -0.4) (0.5 . -0.4) (0.3 . -0.3) (0 . -0.2)) Slur
+  \shape #'((0 . 0) (0 . 0.5) (0 . 0.5) (0 . 0)) PhrasingSlur
+  c8(\( a) a'4 e c\)
+}
 @end lilypond
 
 The @code{\shape} function can also displace the control points of
@@ -4130,35 +4707,41 @@ particular segment are not needed, the empty list can serve as a
 placeholder.  In this example the line break makes the single slur
 look like two:
 
-@lilypond[verbatim,quote,ragged-right,relative=1]
-c4( f g c
-\break
-d,4 c' f, c)
+@lilypond[verbatim,quote,ragged-right]
+\relative {
+  c'4( f g c
+  \break
+  d,4 c' f, c)
+}
 @end lilypond
 
 Changing the shapes of the two halves of the slur makes it clearer
 that the slur continues over the line break:
 
-@lilypond[verbatim,quote,ragged-right,relative=1]
+@lilypond[verbatim,quote,ragged-right]
 % () may be used as a shorthand for ((0 . 0) (0 . 0) (0 . 0) (0 . 0))
 % if any of the segments does not need to be changed
-\shape #'(
-           (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
-           ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
-         ) Slur
-c4( f g c
-\break
-d,4 c' f, c)
+\relative c' {
+  \shape #'(
+             (( 0 . 0) (0 . 0) (0 . 0) (0 . 1))
+             ((0.5 . 1.5) (1 . 0) (0 . 0) (0 . -1.5))
+           ) Slur
+  c4( f g c
+  \break
+  d,4 c' f, c)
+}
 @end lilypond
 
 If an S-shaped curve is required the control points must always be
 adjusted manually --- LilyPond will never select such shapes
 automatically.
 
-@lilypond[verbatim,quote,relative=2]
-c8( e b-> f d' a e-> g)
-\shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
-c8\( e b-> f d' a e-> g\)
+@lilypond[verbatim,quote]
+\relative c'' {
+  c8( e b-> f d' a e-> g)
+  \shape #'((0 . -1) (5.5 . -0.5) (-5.5 . -10.5) (0 . -5.5)) PhrasingSlur
+  c8\( e b-> f d' a e-> g\)
+}
 @end lilypond
 
 @subsubsubheading Specifying control points explicitly
@@ -4180,23 +4763,25 @@ specified relative to a single note.  Here is an example of this.
 It shows one way of indicating a slur extending into alternative
 sections of a volta repeat.
 
-@lilypond[verbatim,quote,relative=2]
-c1
-\repeat volta 3 { c4 d( e f }
-\alternative {
-  { g2) d }
-  {
-    g2
-    % create a slur and move it to a new position
-    % the <> is just an empty chord to carry the slur termination
-    -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
-    f,
-  }
-  {
-    e'2
-    % create a slur and move it to a new position
-    -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
-    f,
+@lilypond[verbatim,quote]
+\relative {
+  c''1
+  \repeat volta 3 { c4 d( e f }
+  \alternative {
+    { g2) d }
+    {
+      g2
+      % create a slur and move it to a new position
+      % the <> is just an empty chord to carry the slur termination
+      -\tweak control-points #'((-2 . 3.8) (-1 . 3.9) (0 . 4) (1 . 3.4)) ( <> )
+      f,
+    }
+    {
+      e'2
+      % create a slur and move it to a new position
+      -\tweak control-points #'((-2 . 3) (-1 . 3.1) (0 . 3.2) (1 . 2.4)) ( <> )
+      f,
+    }
   }
 }
 @end lilypond
@@ -4214,6 +4799,118 @@ Internals Reference:
 @rinternals{TieColumn}.
 
 
+@node Modifying broken spanners
+@subsection Modifying broken spanners
+
+@menu
+* Using alterBroken::
+@end menu
+
+@node Using alterBroken
+@unnumberedsubsubsec Using @code{\alterBroken}
+
+@cindex spanners, modifying
+@cindex broken spanners, modifying
+@funindex \alterBroken
+
+When a spanner crosses a line break or breaks, each piece
+inherits the attributes of the original spanner.  Thus, ordinary
+tweaking of a broken spanner applies the same modifications to
+each of its segments.  In the example below, overriding
+@code{thickness} affects the slur on either side of the line
+break.
+
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+  r2
+  \once\override Slur.thickness = 10
+  c8( d e f
+  \break
+  g8 f e d) r2
+}
+@end lilypond
+
+Independently modifying the appearance of individual pieces
+of a broken spanner is possible with the @code{\alterBroken}
+command.  This command can produce either an @code{\override}
+or a @code{\tweak} of a spanner property.
+
+The syntax for @code{\alterBroken} is
+
+@example
+[-]\alterBroken @var{property} @var{values} @var{item}
+@end example
+
+The argument @var{values} is a list of values, one for each
+broken piece.  If @var{item} is a grob name like @code{Slur} or
+@code{Staff.PianoPedalBracket}, the result is an @code{\override}
+of the specified grob type.  If @var{item} is a music expression
+such as @qq{(} or @qq{[} the result is the same music expression
+with an appropriate tweak applied.
+
+The leading hyphen must be used with the @code{\tweak} form.  Do
+not add it when @code{\alterBroken} is used as an
+@code{\override}.
+
+In its @code{\override} usage, @code{\alterBroken} may be
+prefaced by @code{\once} or @code{\temporary} and reverted by
+using @code{\revert} with @var{property}.
+
+The following code applies an independent @code{\override} to
+each of the slur segments in the previous example:
+
+@lilypond[verbatim,quote,ragged-right]
+\relative c'' {
+  r2
+  \alterBroken thickness #'(10 1) Slur
+  c8( d e f
+  \break
+  g8 f e d) r2
+}
+@end lilypond
+
+The @code{\alterBroken} command may be used with any spanner
+object, including @code{Tie}, @code{PhrasingSlur}, @code{Beam}
+and @code{TextSpanner}.  For example, an editor preparing a
+scholarly edition may wish to indicate the absence of part of a
+phrasing slur in a source by dashing only the segment which has
+been added.  The following example illustrates how this can be
+done, in this case using the @code{\tweak} form of the command:
+
+@lilypond[verbatim,quote,ragged-right]
+% The empty list is conveniently used below, because it is the
+% default setting of dash-definition, resulting in a solid curve.
+\relative {
+  c''2-\alterBroken dash-definition #'(() ((0 1.0 0.4 0.75))) \(e
+  \break
+  g2 e\)
+}
+@end lilypond
+
+It is important to understand that @code{\alterBroken} will set
+each piece of a broken spanner to the corresponding value in
+@var{values}.  When there are fewer values than pieces, any
+additional piece will be assigned the empty list.  This may lead
+to undesired results if the layout property is not set to the
+empty list by default.  In such cases, each segment should be
+assigned an appropriate value.
+
+@knownissues
+Line breaks may occur in different places following changes in
+layout. Settings chosen for @code{\alterBroken} may be unsuitable
+for a spanner that is no longer broken or is split into more
+segments than before.  Explicit use of @code{\break} can guard
+against this situation.
+
+The @code{\alterBroken} command is ineffective for spanner
+properties accessed before line-breaking such as
+@code{direction}.
+
+@seealso
+Extending LilyPond:
+@rextend{Difficult tweaks}.
+
+
 @node Unpure-pure containers
 @subsection Unpure-pure containers
 
@@ -4225,7 +4922,7 @@ Internals Reference:
 
 Unpure-pure containers are useful for overriding @emph{Y-axis} spacing
 calculations - specifically @code{Y-offset} and @code{Y-extent} - with a
-Scheme function instead of a literal (i.e. a number or pair).
+Scheme function instead of a literal (i.e., a number or pair).
 
 For certain grobs, the @code{Y-extent} is based on the @code{stencil}
 property, overriding the stencil property of one of these will
@@ -4273,6 +4970,10 @@ value needed which is then used by the first function to get the real
 value which is then used for fine-tuning much later during the spacing
 process.
 
+@c TODO: The following example supposedly showing a collision no longer
+@c 'works' since 2.18.x. Another example of a collision is needed.
+@c Issue #3512
+
 @lilypond[verbatim,quote,ragged-right]
 #(define (square-line-circle-space grob)
 (let* ((pitch (ly:event-property (ly:grob-property grob 'cause) 'pitch))
@@ -4309,9 +5010,12 @@ the accidentals.  In the second measure, with unpure-pure containers,
 the spacing engine knows the width of the note heads and avoids the
 collision by lengthening the line accordingly.
 
-Usually for simple calculations nearly-identical functions for both the
-@q{unpure} and @q{pure} parts can be used, by only changing the number
-of arguments passed to, and the scope of, the function.
+Usually for simple calculations nearly-identical functions for
+both the @q{unpure} and @q{pure} parts can be used, by only
+changing the number of arguments passed to, and the scope of, the
+function.  This use case is frequent enough that
+@code{ly:make-unpure-pure-container} constructs such a second
+function by default when called with only one function argument.
 
 @warning{If a function is labeled as @q{pure} and it turns out not to
 be, the results can be unexpected.}
@@ -4343,7 +5047,7 @@ code is easy.  The general form of these functions is
 @example
 function =
 #(define-music-function
-     (parser location @var{arg1} @var{arg2} @dots{})
+     (@var{arg1} @var{arg2} @dots{})
      (@var{type1?} @var{type2?} @dots{})
    #@{
      @var{@dots{}music@dots{}}
@@ -4363,19 +5067,14 @@ must return @code{#t}.
 
 @item @code{@var{@dots{}music@dots{}}}
 @tab normal LilyPond input, using @code{$} (in places where only
-Lilypond constructs are allowed) or @code{#} (to use it as a Scheme
+LilyPond constructs are allowed) or @code{#} (to use it as a Scheme
 value or music function argument or music inside of music lists) to
 reference arguments
 (eg. @samp{#arg1}).
 @end multitable
 
-The @code{parser} and @code{location} arguments are mandatory, and
-are used in some advanced situations as described in the
-@q{Extending} manual (see @rextend{Music functions}).  For
-substitution functions, just be sure to include them.
-
-The list of type predicates is also required.  Some of the most
-common type predicates used in music functions are:
+The list of type predicates is required.  Some of the most common
+type predicates used in music functions are:
 
 @example
 boolean?
@@ -4399,7 +5098,7 @@ are also allowed.
 Notation Reference:
 @ref{Predefined type predicates}.
 
-Extending Lilypond:
+Extending LilyPond:
 @rextend{Music functions}.
 
 Installed Files:
@@ -4421,18 +5120,18 @@ setting the padding of a TextScript:
 @lilypond[quote,verbatim,ragged-right]
 padText =
 #(define-music-function
-     (parser location padding)
+     (padding)
      (number?)
    #{
      \once \override TextScript.padding = #padding
    #})
 
-\relative c''' {
-  c4^"piu mosso" b a b
+\relative {
+  c''4^"piu mosso" b a b
   \padText #1.8
-  c4^"piu mosso" d e f
+  c4^"piu mosso" b a b
   \padText #2.6
-  c4^"piu mosso" fis a g
+  c4^"piu mosso" b a b
 }
 @end lilypond
 
@@ -4442,7 +5141,7 @@ as notes for arguments to music functions:
 @lilypond[quote,verbatim,ragged-right]
 custosNote =
 #(define-music-function
-     (parser location note)
+     (note)
      (ly:music?)
    #{
      \tweak NoteHead.stencil #ly:text-interface::print
@@ -4452,24 +5151,57 @@ custosNote =
      #note
    #})
 
-\relative c' { c4 d e f \custosNote g }
+\relative { c'4 d e f \custosNote g }
+@end lilypond
+
+@funindex \etc
+Both of those functions are simple single expressions where only
+the last element of a function call or override is missing.  For
+those particular function definitions, there is a simpler
+alternative syntax, namely just writing out the constant part of
+the expression and replacing its final missing element with
+@code{\etc}:
+
+@lilypond[quote,verbatim,ragged-right]
+padText =
+  \once \override TextScript.padding = \etc
+
+\relative {
+  c''4^"piu mosso" b a b
+  \padText #1.8
+  c4^"piu mosso" b a b
+  \padText #2.6
+  c4^"piu mosso" b a b
+}
+@end lilypond
+
+@lilypond[quote,verbatim,ragged-right]
+custosNote =
+  \tweak NoteHead.stencil #ly:text-interface::print
+  \tweak NoteHead.text
+     \markup \musicglyph #"custodes.mensural.u0"
+  \tweak Stem.stencil ##f
+  \etc
+
+\relative { c'4 d e f \custosNote g }
 @end lilypond
 
+
 Substitution functions with multiple arguments can be defined:
 
 @lilypond[quote,verbatim,ragged-right]
 tempoPadded =
 #(define-music-function
-     (parser location padding tempotext)
+     (padding tempotext)
      (number? markup?)
    #{
      \once \override Score.MetronomeMark.padding = #padding
      \tempo \markup { \bold #tempotext }
    #})
 
-\relative c'' {
+\relative {
   \tempo \markup { "Low tempo" }
-  c4 d e f g1
+  c''4 d e f g1
   \tempoPadded #4.0 "High tempo"
   g4 f e d c1
 }