X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Ftweaks.itely;h=c1e2cc20f35786139ac13340708577cc8f04c185;hb=2755c70c630d8f4a7fc8cd77621a4e3ee05096ab;hp=5802044e422fafcd91b1c267aca81b33810868d8;hpb=a2030063498b24f5b08e10b0e429a12a82abbf2d;p=lilypond.git

diff --git a/Documentation/learning/tweaks.itely b/Documentation/learning/tweaks.itely
index 5802044e42..c1e2cc20f3 100644
--- a/Documentation/learning/tweaks.itely
+++ b/Documentation/learning/tweaks.itely
@@ -8,7 +8,7 @@
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.17.20"
+@c \version "2.19.22"
 
 @node Tweaking output
 @chapter Tweaking output
@@ -107,6 +107,14 @@ ending point, and maybe other properties concerned with their
 shape.  Objects with an extended shape like these are called
 @q{Spanners}.
 
+What is more, there are @q{abstract} grobs which do not print
+anything of their own, but rather collect, position and manage
+other grobs.  Common examples for this are
+@code{DynamicLineSpanner}, @code{BreakAlignment},
+@code{NoteColumn}, @code{VerticalAxisGroup},
+@code{NonMusicalPaperColumn} and similar.  We will see how some of
+these are used later.
+
 It remains to explain what @q{Interfaces} are.  Many objects, even
 though they are quite different, share common features which need to
 be processed in the same way.  For example, all grobs have a color, a
@@ -174,15 +182,16 @@ the types of objects and properties from their names.
 @cindex tweaking methods
 
 @menu
-* The \override command::
-* The \revert command::
-* The \once prefix::
-* The \overrideProperty command::
-* The \tweak command::
+* The override command::
+* The revert command::
+* The once prefix::
+* The overrideProperty command::
+* The tweak command::
+* The single prefix::
 @end menu
 
-@node The \override command
-@unnumberedsubsubsec The @code{\override} command
+@node The override command
+@unnumberedsubsubsec The @code{@bs{}override} command
 
 @cindex override command
 @cindex override syntax
@@ -244,17 +253,19 @@ color of the note head:
 @cindex color property, example
 @cindex NoteHead, example of overriding
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-c4 d
-\override NoteHead.color = #red
-e4 f |
-\override NoteHead.color = #green
-g4 a b c |
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+  c'4 d
+  \override NoteHead.color = #red
+  e4 f |
+  \override NoteHead.color = #green
+  g4 a b c |
+}
 @end lilypond
 
 
-@node The \revert command
-@unnumberedsubsubsec The @code{\revert} command
+@node The revert command
+@unnumberedsubsubsec The @code{@bs{}revert} command
 
 @cindex revert command
 
@@ -280,19 +291,21 @@ of the note head to the default value for the final two notes:
 @cindex color property, example
 @cindex NoteHead, example of overriding
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-c4 d
-\override NoteHead.color = #red
-e4 f |
-\override NoteHead.color = #green
-g4 a
-\revert NoteHead.color
-b4 c |
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+  c'4 d
+  \override NoteHead.color = #red
+  e4 f |
+  \override NoteHead.color = #green
+  g4 a
+  \revert NoteHead.color
+  b4 c |
+}
 @end lilypond
 
 
-@node The \once prefix
-@unnumberedsubsubsec The @code{\once} prefix
+@node The once prefix
+@unnumberedsubsubsec The @code{@bs{}once} prefix
 
 @funindex \once
 @funindex once
@@ -308,26 +321,30 @@ note like this:
 @cindex color property, example
 @cindex NoteHead, example of overriding
 
-@lilypond[quote,verbatim,relative=1]
-c4 d
-\override NoteHead.color = #red
-e4 f |
-\once \override NoteHead.color = #green
-g4 a
-\revert NoteHead.color
-b c |
+@lilypond[quote,verbatim]
+\relative {
+  c'4 d
+  \override NoteHead.color = #red
+  e4 f |
+  \once \override NoteHead.color = #green
+  g4 a
+  \revert NoteHead.color
+  b c |
+}
 @end lilypond
 
 The @code{\once} prefix may also be used in front of many
 predefined commands to limit their effect to one musical moment:
 
-@lilypond[quote,verbatim,relative=1]
-c4 d
-\once \stemDown
-e4 f |
-g4 a
-\once \hideNotes
-b c |
+@lilypond[quote,verbatim]
+\relative {
+  c'4( d)
+  \once \slurDashed
+  e4( f) |
+  g4( a)
+  \once \hideNotes
+  b( c) |
+}
 @end lilypond
 
 However, predefined commands of the form @code{\@dots{}Neutral},
@@ -336,8 +353,8 @@ rather than @code{\override} so prefixing these with @code{\once} has no
 effect.
 
 
-@node The \overrideProperty command
-@unnumberedsubsubsec The @code{\overrideProperty} command
+@node The overrideProperty command
+@unnumberedsubsubsec The @code{@bs{}overrideProperty} command
 
 @cindex overrideProperty command
 
@@ -351,8 +368,8 @@ We mention it here for completeness, but for details see
 @c Maybe explain in a later iteration  -td
 
 
-@node The \tweak command
-@unnumberedsubsubsec The @code{\tweak} command
+@node The tweak command
+@unnumberedsubsubsec The @code{@bs{}tweak} command
 
 @cindex tweak command
 
@@ -373,11 +390,13 @@ middle note head (the E) in a C major chord.  Let's first see what
 @cindex font-size property, example
 @cindex NoteHead, example of overriding
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-<c e g>4
-\once \override NoteHead.font-size = #-3
-<c e g>4
-<c e g>4
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+  <c' e g>4
+  \once \override NoteHead.font-size = #-3
+  <c e g>4
+  <c e g>4
+}
 @end lilypond
 
 We see the override affects @emph{all} the note heads in the chord.
@@ -398,9 +417,11 @@ a chord would be changed in this way:
 @cindex font-size property, example
 @cindex @code{\tweak}, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-<c e g>4
-<c \tweak font-size #-3 e g>4
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+  <c' e g>4
+  <c \tweak font-size #-3 e g>4
+}
 @end lilypond
 
 Note that the syntax of @code{\tweak} is different from that of the
@@ -420,8 +441,8 @@ a series of articulations, as shown here:
 @cindex color property, example
 @cindex @code{\tweak}, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-a4^"Black"
+@lilypond[quote,fragment,ragged-right,verbatim]
+a'4^"Black"
   -\tweak color #red ^"Red"
   -\tweak color #green _"Green"
 @end lilypond
@@ -441,16 +462,16 @@ directly from the following event.  It is still possible to use
 the layout object, provided that LilyPond can trace its origin back to
 the original event:
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-<\tweak Accidental.color #red   cis4
- \tweak Accidental.color #green es
- g>
+@lilypond[quote,fragment,ragged-right,verbatim]
+<\tweak Accidental.color #red   cis''4
+ \tweak Accidental.color #green es''
+ g''>
 @end lilypond
 
 This long form of the @code{\tweak} command can be described as
 
 @example
-\tweak @var{layout-object}.@var{layout-property} @var{value}
+\tweak @var{LayoutObject}.@var{layout-property} #@var{value}
 @end example
 
 @cindex tuplets, nested
@@ -477,13 +498,15 @@ printed in red on the first short tuplet bracket.
 @cindex direction property, example
 @cindex color property, example
 
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
-\tweak direction #up
-\tuplet 3/4 {
-  \tweak color #red
-  \tuplet 3/2 { c8[ c c] }
-  \tuplet 3/2 { c8[ c c] }
-  \tuplet 3/2 { c8[ c c] }
+@lilypond[quote,ragged-right,verbatim]
+\relative c'' {
+  \tweak direction #up
+  \tuplet 3/4 {
+    \tweak color #red
+    \tuplet 3/2 { c8[ c c] }
+    \tuplet 3/2 { c8[ c c] }
+    \tuplet 3/2 { c8[ c c] }
+  }
 }
 @end lilypond
 
@@ -496,15 +519,17 @@ appearance may be modified in the usual way with
 @cindex transparent property, example
 @cindex TupletNumber, example of overriding
 
-@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
-\tuplet 3/2 { c8[ c c] }
-\once \override TupletNumber.text = #tuplet-number::calc-fraction-text
-\tuplet 3/2 {
-  c8[ c]
-  c8[ c]
-  \once \override TupletNumber.transparent = ##t
-  \tuplet 3/2 { c8[ c c] }
-  \tuplet 3/2 { c8[ c c] }
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+  \tuplet 3/2 { c'8[ c c] }
+  \once \override TupletNumber.text = #tuplet-number::calc-fraction-text
+  \tuplet 3/2 {
+    c8[ c]
+    c8[ c]
+    \once \override TupletNumber.transparent = ##t
+    \tuplet 3/2 { c8[ c c] }
+    \tuplet 3/2 { c8[ c c] }
+  }
 }
 @end lilypond
 
@@ -513,6 +538,60 @@ appearance may be modified in the usual way with
 Notation Reference:
 @ruser{The tweak command}.
 
+@node The single prefix
+@unnumberedsubsubsec The @code{@bs{}single} prefix
+
+@funindex \single
+@cindex tweak, generated from override
+
+Suppose we wanted to emphasize particular note heads by coloring them
+red and increasing their size, and to make it easy suppose also we
+have defined a function to do this:
+
+@lilypond[quote,verbatim]
+emphNoteHead = {
+  \override NoteHead.color = #red
+  \override NoteHead.font-size = 2
+}
+\relative {
+  c''4 a \once \emphNoteHead f d |
+}
+@end lilypond
+
+The @code{\once} prefix works fine to emphasize single notes or
+complete chords, but it cannot be used to emphasize a single note
+@emph{within} a chord.  Earlier we have seen how @code{\tweak} can
+be used to do this, see
+@ref{The tweak command,,The @code{@bs{}tweak} command}.  But
+@code{\tweak} cannot be used with a function; that's where
+@code{\single} comes in:
+
+@lilypond[quote,verbatim]
+emphNoteHead = {
+  \override NoteHead.color = #red
+  \override NoteHead.font-size = 2
+}
+\relative {
+   <c'' a \single \emphNoteHead f d>4
+}
+@end lilypond
+
+In summary, @code{\single} converts overrides into tweaks so when
+there are several objects at the same point in musical time (like
+noteheads in a chord), @code{\single} will only affect a single one,
+the one generated by the immediately following music expression, in
+contrast to @code{\once} which will affect all of those objects.
+
+By using @code{\single} in this way any shorthand function
+containing just overrides may be applied to individual notes in a
+chord.  However, @code{\single} does not convert @code{\revert},
+@code{\set} or @code{\unset} into tweaks.
+
+@seealso
+Learning Manual:
+@ref{The tweak command,,The @code{@bs{}tweak} command},
+@ref{Using variables for layout adjustments}.
+
 
 @node The Internals Reference manual
 @section The Internals Reference manual
@@ -563,12 +642,12 @@ music:
 
 @c Mozart, Die Zauberflöte Nr.7 Duett
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 {
   \key es \major
   \time 6/8
-  {
-    r4 bes8 bes[( g]) g |
+  \relative {
+    r4 bes'8 bes[( g]) g |
     g8[( es]) es d[( f]) as |
     as8 g
   }
@@ -648,14 +727,14 @@ close to it.}  Let's do that:
 @cindex Slur example of overriding
 @cindex thickness property, example
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 {
   \key es \major
   \time 6/8
-  {
+  \relative {
     % Increase thickness of all following slurs from 1.2 to 5.0
     \override Slur.thickness = #5.0
-    r4 bes8 bes[( g]) g |
+    r4 bes'8 bes[( g]) g |
     g8[( es]) es d[( f]) as |
     as8 g
   }
@@ -717,12 +796,12 @@ repositioned as follows:
 @cindex Slur, example of overriding
 @cindex thickness property, example
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 {
   \key es \major
   \time 6/8
-  {
-    r4 bes8
+  \relative {
+    r4 bes'8
     % Increase thickness of immediately following slur only
     \once \override Slur.thickness = #5.0
     bes8[( g]) g |
@@ -757,12 +836,12 @@ the slurs begin:
 @cindex Slur, example of overriding
 @cindex thickness property, example
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 {
   \key es \major
   \time 6/8
-  {
-    r4 bes8
+  \relative {
+    r4 bes'8
     % Increase thickness of immediately following slur only
     \once \override Slur.thickness = #5.0
     bes[( g]) g |
@@ -785,12 +864,12 @@ after the second slur:
 @cindex Slur, example of overriding
 @cindex thickness property, example
 
-@lilypond[quote,verbatim,relative=2]
+@lilypond[quote,verbatim]
 {
   \key es \major
   \time 6/8
-  {
-    r4 bes8
+  \relative {
+    r4 bes'8
     % Increase thickness of all following slurs from 1.2 to 5.0
     \override Slur.thickness = #5.0
     bes[( g]) g |
@@ -892,12 +971,12 @@ like so:
 @cindex LyricText, example of overriding
 @cindex @code{\addlyrics}, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,ragged-right,verbatim]
 {
   \key es \major
   \time 6/8
-  {
-    r4 bes8 bes[( g]) g |
+  \relative {
+    r4 bes'8 bes[( g]) g |
     g8[( es]) es d[( f]) as |
     as8 g
   }
@@ -1062,11 +1141,11 @@ the implied Context, @code{Voice}:
 @cindex BarLine, example of overriding
 @cindex stencil property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \override BarLine.stencil = ##f
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1087,11 +1166,11 @@ it by adding the correct context:
 @cindex BarLine, example of overriding
 @cindex stencil property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \override Staff.BarLine.stencil = ##f
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1102,11 +1181,11 @@ property to @code{#f} is such a frequent operation that there is a
 shorthand for it called @code{\omit}:
 @funindex \omit
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \omit Staff.BarLine
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1120,9 +1199,9 @@ correct processing.  For example, errors will be generated if the
 @code{point-stencil} function, which sets the stencil to an object
 with zero size:
 
-@lilypond[quote,verbatim,relative=2]
-{
-  c4 c
+@lilypond[quote,verbatim]
+\relative {
+  c''4 c
   \once \override NoteHead.stencil = #point-stencil
   c4 c
 }
@@ -1149,11 +1228,11 @@ required, as always, to precede the value itself in the
 @cindex BarLine, example of overriding
 @cindex break-visibility property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \override Staff.BarLine.break-visibility = ##(#f #f #f)
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1182,11 +1261,11 @@ transparent is:
 @cindex TimeSignature, example of overriding
 @cindex transparent property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \override Staff.TimeSignature.transparent = ##t
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1198,11 +1277,11 @@ frequent operation, so we have a shorthand for it called
 @code{\hide}:
 @funindex \hide
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \hide Staff.TimeSignature
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1220,11 +1299,11 @@ instead:
 @cindex TimeSignature, example of overriding
 @cindex stencil property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \omit Staff.TimeSignature
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1264,11 +1343,11 @@ we write:
 @cindex BarLine, example of overriding
 @cindex color property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \override Staff.BarLine.color = #white
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1298,11 +1377,11 @@ converts X11 color symbols into the list of internal values like this:
 @cindex BarLine, example of overriding
 @cindex color property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \override Staff.BarLine.color = #(x11-color 'white)
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1329,11 +1408,11 @@ and to white it should be @code{(rgb-color 1 1 1)}:
 @cindex BarLine, example of overriding
 @cindex color property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \override Staff.BarLine.color = #(rgb-color 1 1 1)
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1354,8 +1433,8 @@ various shades of grey:
 @cindex color property, example
 @cindex x11-color, example of using
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-{
+@lilypond[quote,ragged-right,verbatim]
+\relative {
   \time 12/16
   \override Staff.StaffSymbol.color = #(x11-color 'grey30)
   \override Staff.TimeSignature.color = #(x11-color 'grey60)
@@ -1363,7 +1442,7 @@ various shades of grey:
   \override Voice.NoteHead.color = #(x11-color 'grey85)
   \override Voice.Stem.color = #(x11-color 'grey85)
   \override Staff.BarLine.color = #(x11-color 'grey10)
-  c4 b8 c d16 c d8 |
+  c''4 b8 c d16 c d8 |
   g,8 a16 b8 c d4 e16 |
   e8
 }
@@ -1395,10 +1474,10 @@ how to introduce a new temporary staff, as in an @rglos{ossia}.
 @cindex alignAboveContext property, example
 @cindex @code{\with}, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,ragged-right,verbatim]
 \new Staff ="main" {
-  \relative g' {
-    r4 g8 g c4 c8 d |
+  \relative {
+    r4 g'8 g c4 c8 d |
     e4 r8
     <<
       { f8 c c }
@@ -1422,10 +1501,10 @@ we simply set the stencil of each to @code{#f}, as follows:
 @cindex Clef, example of overriding
 @cindex TimeSignature, example of overriding
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,ragged-right,verbatim]
 \new Staff ="main" {
-  \relative g' {
-    r4 g8 g c4 c8 d |
+  \relative {
+    r4 g'8 g c4 c8 d |
     e4 r8
     <<
       { f8 c c }
@@ -1485,10 +1564,10 @@ So we could replace the example above with
 @cindex Clef, example of overriding
 @cindex TimeSignature, example of overriding
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,ragged-right,verbatim]
 \new Staff ="main" {
-  \relative g' {
-    r4 g8 g c4 c8 d |
+  \relative {
+    r4 g'8 g c4 c8 d |
     e4 r8
     <<
       { f8 c c }
@@ -1510,10 +1589,10 @@ It turns out that we can also employ the shorthands @code{\hide}
 and @code{\omit} for setting the @code{transparent} property and
 clearing the @code{stencil} here, leading to the result
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,ragged-right,verbatim]
 \new Staff ="main" {
-  \relative g' {
-    r4 g8 g c4 c8 d |
+  \relative {
+    r4 g'8 g c4 c8 d |
     e4 r8
     <<
       { f8 c c }
@@ -1574,10 +1653,10 @@ Let's try it in our ossia example:
 @cindex TimeSignature, example of overriding
 @cindex fontSize property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,ragged-right,verbatim]
 \new Staff ="main" {
-  \relative g' {
-    r4 g8 g c4 c8 d |
+  \relative {
+    r4 g'8 g c4 c8 d |
     e4 r8
     <<
       { f8 c c }
@@ -1640,10 +1719,10 @@ objects in proportion.  It is used like this:
 @cindex staff-space property, example
 @cindex stencil property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,ragged-right,verbatim]
 \new Staff ="main" {
-  \relative g' {
-    r4 g8 g c4 c8 d |
+  \relative {
+    r4 g'8 g c4 c8 d |
     e4 r8
     <<
       { f8 c c }
@@ -1747,11 +1826,11 @@ under @q{Text2}.
 
 @cindex markup example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-c2^"Text1"
-c2^"Text2" |
-c2^"Text3"
-c2^"Text4" |
+@lilypond[quote,fragment,ragged-right,verbatim]
+c''2^"Text1"
+c''2^"Text2" |
+c''2^"Text3"
+c''2^"Text4" |
 @end lilypond
 
 Staves are also positioned, by default, as closely together as
@@ -1764,10 +1843,10 @@ this @q{nestling} of the notes on adjacent staves:
 @lilypond[quote,ragged-right,verbatim]
 <<
   \new Staff {
-    \relative c' { c4 a, }
+    \relative { c'4 a, }
   }
   \new Staff {
-    \relative c'''' { c4 a, }
+    \relative { c''''4 a, }
   }
 >>
 @end lilypond
@@ -1806,30 +1885,30 @@ automatically when @code{direction} is set.
 @cindex center
 @cindex neutral
 
-The following example shows in bar 1 the default behavior of stems,
-with those on high notes pointing down and those on low notes pointing
-up, followed by four notes with all stems forced down, four notes with
-all stems forced up, and finally four notes reverted back to the
-default behavior.
+The following example shows the default positioning of slurs in the
+first bar, with slurs starting on high notes positioned above the notes
+and those starting on low notes positioned below, followed by a bar
+with both slurs forced down, a bar with both slurs forced up, and
+finally a bar with both slurs reverted back to the default behavior.
 
-@cindex Stem, example of overriding
+@cindex Slur, example of overriding
 @cindex direction property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-a4 g c a |
-\override Stem.direction = #DOWN
-a4 g c a |
-\override Stem.direction = #UP
-a4 g c a |
-\revert Stem.direction
-a4 g c a |
+@lilypond[quote,fragment,verbatim]
+a'4( g') c''( a') |
+\override Slur.direction = #DOWN
+a'4( g') c''( a') |
+\override Slur.direction = #UP
+a'4( g') c''( a') |
+\revert Slur.direction
+a'4( g') c''( a') |
 @end lilypond
 
-Here we use the constants @code{DOWN} and @code{UP}.
+Here we have used the constants @code{DOWN} and @code{UP}.
 These have the values @w{@code{-1}} and @code{+1} respectively, and
 these numerical values may be used instead.  The value @code{0}
 may also be used in some cases.  It is simply treated as meaning
-@code{UP} for stems, but for some objects it means @q{center}.
+@code{UP} for slurs, but for some objects it means @q{center}.
 There is a constant, @code{CENTER} which has the value @code{0}.
 
 However, these explicit overrides are not usually used, as there are
@@ -1880,12 +1959,20 @@ the commonest.  The meaning of each is stated where it is not obvious.
 @end multitable
 
 The neutral/normal variants of these commands are implemented
-using @code{\revert} and may @strong{not} be
+using @code{\revert} and these may @strong{not} be
 preceded by @code{\once}.  If you wish to limit the
 effect of the other commands (which are implemented using
 @code{\override}) to a single timestep, you can precede them with
 @code{\once} like you would do with explicit overrides.
 
+Or, if just a single layout object needs to be forced up or down, the
+direction indicators, @code{^} or @code{_}, may be used:
+
+@lilypond[quote,fragment,verbatim]
+a'4( g') c''( a') |
+a'4^( g') c''_( a') |
+@end lilypond
+
 @node Fingering
 @unnumberedsubsubsec Fingering
 
@@ -1907,12 +1994,14 @@ specifying @code{DOWN} and @code{UP}:
 @cindex Fingering, example of overriding
 @cindex direction property, example
 
-@lilypond[quote,verbatim,relative=2]
-c4-5 a-3 f-1 c'-5 |
-\override Fingering.direction = #DOWN
-c4-5 a-3 f-1 c'-5 |
-\override Fingering.direction = #UP
-c4-5 a-3 f-1 c'-5 |
+@lilypond[quote,verbatim]
+\relative {
+  c''4-5 a-3 f-1 c'-5 |
+  \override Fingering.direction = #DOWN
+  c4-5 a-3 f-1 c'-5 |
+  \override Fingering.direction = #UP
+  c4-5 a-3 f-1 c'-5 |
+}
 @end lilypond
 
 However, overriding the @code{direction} property is not the
@@ -1923,10 +2012,12 @@ example using this method:
 
 @cindex fingering example
 
-@lilypond[quote,verbatim,relative=2]
-c4-5 a-3 f-1 c'-5 |
-c4_5 a_3 f_1 c'_5 |
-c4^5 a^3 f^1 c'^5 |
+@lilypond[quote,verbatim]
+\relative {
+  c''4-5 a-3 f-1 c'-5 |
+  c4_5 a_3 f_1 c'_5 |
+  c4^5 a^3 f^1 c'^5 |
+}
 @end lilypond
 
 The @code{direction} property is ignored for chords, but the
@@ -1936,10 +2027,12 @@ notes of a chord, as shown:
 
 @cindex fingering example
 
-@lilypond[quote,verbatim,relative=2]
-<c-5 g-3>4
-<c-5 g-3 e-2>4
-<c-5 g-3 e-2 c-1>4
+@lilypond[quote,verbatim]
+\relative {
+  <c''-5 g-3>4
+  <c-5 g-3 e-2>4
+  <c-5 g-3 e-2 c-1>4
+}
 @end lilypond
 
 @noindent
@@ -1948,10 +2041,12 @@ individual fingering numbers above or below:
 
 @cindex fingering example
 
-@lilypond[quote,verbatim,relative=2]
-<c-5 g-3 e-2 c-1>4
-<c^5 g_3 e_2 c_1>4
-<c^5 g^3 e^2 c_1>4
+@lilypond[quote,verbatim]
+\relative {
+  <c''-5 g-3 e-2 c-1>4
+  <c^5 g_3 e_2 c_1>4
+  <c^5 g^3 e^2 c_1>4
+}
 @end lilypond
 
 Even greater control over the placement of fingering of the
@@ -1989,22 +2084,24 @@ Here are a few examples:
 @cindex @code{\set}, example of using
 @cindex fingeringOrientations property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-\set fingeringOrientations = #'(left)
-<f-2>4
-<c-1 e-2 g-3 b-5>4
-\set fingeringOrientations = #'(left)
-<f-2>4
-<c-1 e-2 g-3 b-5>4 |
-\set fingeringOrientations = #'(up left down)
-<f-2>4
-<c-1 e-2 g-3 b-5>4
-\set fingeringOrientations = #'(up left)
-<f-2>4
-<c-1 e-2 g-3 b-5>4 |
-\set fingeringOrientations = #'(right)
-<f-2>4
-<c-1 e-2 g-3 b-5>4
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+  \set fingeringOrientations = #'(left)
+  <f'-2>4
+  <c-1 e-2 g-3 b-5>4
+  \set fingeringOrientations = #'(left)
+  <f-2>4
+  <c-1 e-2 g-3 b-5>4 |
+  \set fingeringOrientations = #'(up left down)
+  <f-2>4
+  <c-1 e-2 g-3 b-5>4
+  \set fingeringOrientations = #'(up left)
+  <f-2>4
+  <c-1 e-2 g-3 b-5>4 |
+  \set fingeringOrientations = #'(right)
+  <f-2>4
+  <c-1 e-2 g-3 b-5>4
+}
 @end lilypond
 
 @noindent
@@ -2013,23 +2110,25 @@ could be reduced.  The default value can be seen from the
 @code{Fingering} object in the IR to be @w{@code{-5}}, so let's
 try @w{@code{-7}}:
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-\override Fingering.font-size = #-7
-\set fingeringOrientations = #'(left)
-<f-2>4
-<c-1 e-2 g-3 b-5>4
-\set fingeringOrientations = #'(left)
-<f-2>4
-<c-1 e-2 g-3 b-5>4 |
-\set fingeringOrientations = #'(up left down)
-<f-2>4
-<c-1 e-2 g-3 b-5>4
-\set fingeringOrientations = #'(up left)
-<f-2>4
-<c-1 e-2 g-3 b-5>4 |
-\set fingeringOrientations = #'(right)
-<f-2>4
-<c-1 e-2 g-3 b-5>4
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+  \override Fingering.font-size = #-7
+  \set fingeringOrientations = #'(left)
+  <f'-2>4
+  <c-1 e-2 g-3 b-5>4
+  \set fingeringOrientations = #'(left)
+  <f-2>4
+  <c-1 e-2 g-3 b-5>4 |
+  \set fingeringOrientations = #'(up left down)
+  <f-2>4
+  <c-1 e-2 g-3 b-5>4
+  \set fingeringOrientations = #'(up left)
+  <f-2>4
+  <c-1 e-2 g-3 b-5>4 |
+  \set fingeringOrientations = #'(right)
+  <f-2>4
+  <c-1 e-2 g-3 b-5>4
+}
 @end lilypond
 
 @node Outside-staff objects
@@ -2041,7 +2140,7 @@ positioning is not optimum.
 
 @menu
 * The outside-staff-priority property::
-* The \textLengthOn command::
+* The textLengthOn command::
 * Dynamics placement::
 * Grob sizing::
 @end menu
@@ -2124,7 +2223,7 @@ these.
 @cindex TextSpanner, example of overriding
 @cindex bound-details property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+@lilypond[quote,fragment,ragged-right,verbatim]
 % Set details for later Text Spanner
 \override TextSpanner.bound-details.left.text
     = \markup { \small \bold Slower }
@@ -2132,18 +2231,18 @@ these.
 \dynamicUp
 % Start Ottava Bracket
 \ottava #1
-c'4 \startTextSpan
+c''4 \startTextSpan
 % Add Dynamic Text and hairpin
-c4\pp\<
-c4
+c''4\pp\<
+c''4
 % Add Text Script
-c4^Text |
-c4 c
+c''4^Text |
+c''4 c''
 % Add Dynamic Text and terminate hairpin
-c4\ff c \stopTextSpan |
+c''4\ff c'' \stopTextSpan |
 % Stop Ottava Bracket
 \ottava #0
-c,4 c c c |
+c'4 c' c' c' |
 @end lilypond
 
 This example also shows how to create Text Spanners --
@@ -2174,7 +2273,7 @@ in the @code{Staff} context:
 @cindex TextSpanner, example of overriding
 @cindex bound-details property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+@lilypond[quote,fragment,ragged-right,verbatim]
 % Set details for later Text Spanner
 \override TextSpanner.bound-details.left.text
     = \markup { \small \bold Slower }
@@ -2184,19 +2283,19 @@ in the @code{Staff} context:
 \once \override Staff.OttavaBracket.outside-staff-priority = #340
 % Start Ottava Bracket
 \ottava #1
-c'4 \startTextSpan
+c''4 \startTextSpan
 % Add Dynamic Text
-c4\pp
+c''4\pp
 % Add Dynamic Line Spanner
-c4\<
+c''4\<
 % Add Text Script
-c4^Text |
-c4 c
+c''4^Text |
+c''4 c''
 % Add Dynamic Text
-c4\ff c \stopTextSpan |
+c''4\ff c'' \stopTextSpan |
 % Stop Ottava Bracket
 \ottava #0
-c,4 c c c |
+c'4 c' c' c' |
 @end lilypond
 
 Note that some of these objects, in particular bar numbers,
@@ -2221,14 +2320,16 @@ can be set to a numerical value to cause it to be placed along with
 other outside-staff objects according to that value.  Here's an
 example showing the effect of the two methods:
 
-@lilypond[quote,verbatim,relative=2]
-c4( c^\markup { \tiny \sharp } d4.) c8 |
-c4(
-\once \override TextScript.avoid-slur = #'inside
-\once \override TextScript.outside-staff-priority = ##f
-c4^\markup { \tiny \sharp } d4.) c8 |
-\once \override Slur.outside-staff-priority = #500
-c4( c^\markup { \tiny \sharp } d4.) c8 |
+@lilypond[quote,verbatim]
+\relative c'' {
+  c4( c^\markup { \tiny \sharp } d4.) c8 |
+  c4(
+    \once \override TextScript.avoid-slur = #'inside
+    \once \override TextScript.outside-staff-priority = ##f
+    c4^\markup { \tiny \sharp } d4.) c8 |
+  \once \override Slur.outside-staff-priority = #500
+    c4( c^\markup { \tiny \sharp } d4.) c8 |
+}
 @end lilypond
 
 Changing the @code{outside-staff-priority} can also be used to
@@ -2243,12 +2344,12 @@ in the IR or in the tables above, and increase the priority of
 @cindex TextScript, example of overriding
 @cindex outside-staff-priority property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-c2^"Text1"
-c2^"Text2" |
+@lilypond[quote,fragment,ragged-right,verbatim]
+c''2^"Text1"
+c''2^"Text2" |
 \once \override TextScript.outside-staff-priority = #500
-c2^"Text3"
-c2^"Text4" |
+c''2^"Text3"
+c''2^"Text4" |
 @end lilypond
 
 This certainly lifts @qq{Text3} above @qq{Text4} but it also lifts it
@@ -2259,8 +2360,8 @@ clearly will need to space the notes out horizontally to make more
 room for the text.  This is done using the @code{textLengthOn}
 command.
 
-@node The \textLengthOn command
-@unnumberedsubsubsec The @code{\textLengthOn} command
+@node The textLengthOn command
+@unnumberedsubsubsec The @code{@bs{}textLengthOn} command
 
 @cindex notes, spreading out with text
 
@@ -2274,12 +2375,12 @@ as far as laying out the music is concerned.  The @code{\textLengthOn}
 command reverses this behavior, causing the notes to be spaced
 out as far as is necessary to accommodate the text:
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,fragment,ragged-right,verbatim]
 \textLengthOn  % Cause notes to space out to accommodate text
-c2^"Text1"
-c2^"Text2" |
-c2^"Text3"
-c2^"Text4" |
+c''2^"Text1"
+c''2^"Text2" |
+c''2^"Text3"
+c''2^"Text4" |
 @end lilypond
 
 The command to revert to the default behavior is
@@ -2300,25 +2401,27 @@ example to show how markup text interacts with such notes.
 @cindex TextScript, example of overriding
 @cindex outside-staff-priority property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-% This markup is short enough to fit without collision
-c2^"Tex" c'' |
-R1 |
-
-% This is too long to fit, so it is displaced upwards
-c,,2^"Text" c'' |
-R1 |
-
-% Turn off collision avoidance
-\once \override TextScript.outside-staff-priority = ##f
-c,,2^"Long Text   " c'' |
-R1 |
-
-% Turn off collision avoidance
-\once \override TextScript.outside-staff-priority = ##f
-\textLengthOn        % and turn on textLengthOn
-c,,2^"Long Text   "  % Spaces at end are honored
-c''2 |
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+  % This markup is short enough to fit without collision
+  c''2^"Tex" c'' |
+  R1 |
+
+  % This is too long to fit, so it is displaced upwards
+  c,,2^"Text" c'' |
+  R1 |
+
+  % Turn off collision avoidance
+  \once \override TextScript.outside-staff-priority = ##f
+  c,,2^"Long Text   " c'' |
+  R1 |
+
+  % Turn off collision avoidance
+  \once \override TextScript.outside-staff-priority = ##f
+  \textLengthOn        % and turn on textLengthOn
+  c,,2^"Long Text   "  % Spaces at end are honored
+  c''2 |
+}
 @end lilypond
 
 @node Dynamics placement
@@ -2335,13 +2438,15 @@ all within-staff objects such as phrasing slurs and bar numbers.
 This can give quite acceptable results, as this example
 shows:
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-\clef "bass"
-\key aes \major
-\time 9/8
-\dynamicUp
-bes4.~\f\< \( bes4 bes8 des4\ff\> c16 bes\! |
-ees,2.~\)\mf ees4 r8 |
+@lilypond[quote,ragged-right,verbatim]
+\relative {
+  \clef "bass"
+  \key aes \major
+  \time 9/8
+  \dynamicUp
+  bes4.~\f\< \( bes4 bes8 des4\ff\> c16 bes\! |
+  ees,2.~\)\mf ees4 r8 |
+}
 @end lilypond
 
 However, if the notes and attached dynamics are close
@@ -2350,9 +2455,9 @@ by displacing later dynamic markings further away, but this may
 not be the optimum placement, as this rather artificial example
 shows:
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,ragged-right,verbatim,fragment]
 \dynamicUp
-a4\f b\mf a\mp b\p
+\relative { a'4\f b\mf a\mp b\p }
 @end lilypond
 
 @noindent
@@ -2405,11 +2510,11 @@ Let's see if this works in our previous example:
 @cindex extra-spacing-width property, example
 
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,ragged-right,verbatim,fragment]
 \dynamicUp
 % Extend width by 1 staff space
 \override DynamicText.extra-spacing-width = #'(-0.5 . 0.5)
-a4\f b\mf a\mp b\p
+\relative { a'4\f b\mf a\mp b\p }
 @end lilypond
 
 @noindent
@@ -2613,7 +2718,7 @@ to remember is that the spacing between objects in a
 of the @code{StaffGrouper}. Spacing from ungrouped staves
 (like @code{Lyrics} and @code{Staff}) is controlled by the
 variables of the @code{VerticalAxisGroup}.  See the
-@ruser{Flexible vertical spacing \paper variables} and
+@ruser{Flexible vertical spacing paper variables} and
 @ruser{Flexible vertical spacing within systems} for more
 details.
 
@@ -2765,27 +2870,58 @@ of the staff in half staff-spaces.  It is useful in resolving
 collisions between layout objects like multi-measure rests, ties
 and notes in different voices.
 
+@item
+@code{horizontal-shift}
+
+@cindex horizontal-shift property
+@cindex note column
+@cindex note collisions
+@cindex collisions, notes
+@cindex shift commands
+@funindex \shiftOff
+@funindex shiftOff
+@funindex \shiftOn
+@funindex shiftOn
+@funindex \shiftOnn
+@funindex shiftOnn
+@funindex \shiftOnnn
+@funindex shiftOnnn
+
+Within a voice, all the notes occuring at the same musical moment are
+grouped into a note column, and a @code{NoteColumn} object is created
+to control the horizontal positioning of that group of notes (see
+@qq{Note columns} in @ref{Explicitly instantiating voices}).  If
+@emph{and only if} two or more note columns within a single Staff
+context, both with stems in the same direction, occur at the same
+musical moment, the values of their @code{horizontal-shift} properties
+are used to rank them and the columns in the higher ranks are
+progessively offset to avoid collisions of the noteheads.  This
+property is set by the @code{\voiceXXX} commands and may be overridden
+directly with an @code{\override} command or, more usually, by the
+@code{\shiftOn} commands.  Note that this property is used to
+@emph{rank} the note columns for off-setting - it does not specify the
+magnitude of the offset, which is progressively increased in steps
+based on the note head's width for each rank.  The steps are usually
+of half a note head's width, but may be a full note head's width when
+a closely spaced group of notes is involved.
+
 @item
 @code{force-hshift}
 
 @cindex force-hshift property
 
-Closely spaced notes in a chord, or notes occurring at the same
-time in different voices, are arranged in two, occasionally more,
-columns to prevent the note heads overlapping.  These are called
-note columns, and an object called @code{NoteColumn} is created
-to lay out the notes in that column.
-
 The @code{force-hshift} property is a property of a @code{NoteColumn}
 (actually of the @code{note-column-interface}).  Changing it permits a
-note column to be moved in units appropriate to a note column,
-viz. the note head width of the first voice note.  It should be used
-in complex situations where the normal @code{\shiftOn} commands (see
+note column to be moved in situations where the note columns overlap.
+Note that it has no effect on note columns that do not overlap.
+It is specified in units appropriate to a note column, viz. the note
+head width of the first voice note.  It should be used in complex
+situations where the normal @code{\shiftOn} commands (see
 @ref{Explicitly instantiating voices}) do not resolve the note
-conflict.  It is preferable to the @code{extra-offset} property for
-this purpose as there is no need to work out the distance in
-staff-spaces, and moving the notes into or out of a @code{NoteColumn}
-affects other actions such as merging note heads.
+conflict satisfactorily.  It is preferable to the @code{extra-offset}
+property for this purpose as there is no need to work out the distance
+in staff-spaces, and moving the notes into or out of a
+@code{NoteColumn} affects other actions such as merging note heads.
 
 @end itemize
 
@@ -2887,8 +3023,8 @@ above or below notes.
 @cindex Script, example of overriding
 @cindex padding property, example
 
-@lilypond[quote,fragment,relative=1,verbatim]
-c2\fermata
+@lilypond[quote,fragment,verbatim]
+c'2\fermata
 \override Script.padding = #3
 b2\fermata
 @end lilypond
@@ -2896,15 +3032,15 @@ b2\fermata
 @cindex MetronomeMark, example of overriding
 @cindex padding property, example
 
-@lilypond[quote,fragment,relative=1,verbatim]
+@lilypond[quote,fragment,verbatim]
 % This will not work, see below
 \override MetronomeMark.padding = #3
 \tempo 4 = 120
-c1 |
+c'1 |
 % This works
 \override Score.MetronomeMark.padding = #3
 \tempo 4 = 80
-d1 |
+d'1 |
 @end lilypond
 
 Note in the second example how important it is to figure out what
@@ -2939,8 +3075,8 @@ stencil with a markup containing the desired symbol(s), like this:
 
 @lilypond[quote,ragged-right,verbatim]
 sesquisharp = \markup { \sesquisharp }
-\relative c'' {
-  c4
+\relative {
+  c''4
   % This prints a sesquisharp but the spacing is too small
   \once \override Accidental.stencil = #ly:text-interface::print
   \once \override Accidental.text = #sesquisharp
@@ -2983,9 +3119,9 @@ example taken from the previous section:
 @cindex DynamicLineSpanner, example of overriding
 @cindex staff-padding property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+@lilypond[quote,fragment,ragged-right,verbatim]
 \override DynamicLineSpanner.staff-padding = #3
-a4\f b\mf a\p b\mp
+\relative { a'4\f b\mf a\p b\mp }
 @end lilypond
 
 
@@ -2999,11 +3135,11 @@ right edge with the reference point of the parent note:
 @cindex StringNumber, example of overriding
 @cindex self-alignment-X property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=3]
+@lilypond[quote,fragment,ragged-right,verbatim]
 \voiceOne
-<a\2>
+<a''\2>
 \once \override StringNumber.self-alignment-X = #RIGHT
-<a\2>
+<a''\2>
 @end lilypond
 
 @node The staff-position property
@@ -3019,8 +3155,8 @@ handling between notes and between notes and rests is done only
 for notes and rests that occur at the same time.  Here's an
 example of a collision of this type:
 
-@lilypond[quote,verbatim,fragment,ragged-right, relative=1]
-<< { c4 c c c } \\ { R1 } >>
+@lilypond[quote,verbatim,ragged-right]
+<< \relative { c'4 c c c } \\ { R1 } >>
 @end lilypond
 
 The best solution here is to move the multimeasure rest down, since the
@@ -3032,9 +3168,9 @@ to move it, say, four half-staff spaces down to @w{@code{-8}}.
 @cindex MultiMeasureRest, example of overriding
 @cindex staff-position property, example
 
-@lilypond[quote,verbatim,fragment,ragged-right, relative=1]
+@lilypond[quote,verbatim,ragged-right]
 <<
-  { c4 c c c }
+  \relative { c'4 c c c }
   \\
   \override MultiMeasureRest.staff-position = #-8
   { R1 }
@@ -3061,11 +3197,10 @@ the left, and 1.8 staff space downwards:
 @cindex Fingering, example of overriding
 @cindex extra-offset property, example
 
-@lilypond[quote,fragment,relative=1,verbatim]
-\stemUp
-f4-5
+@lilypond[quote,fragment,verbatim]
+f'4-5
 \once \override Fingering.extra-offset = #'(-0.3 . -1.8)
-f4-5
+f'4-5
 @end lilypond
 
 
@@ -3085,8 +3220,8 @@ manually.
 
 Here's an example in which the phrasing slur and slur collide:
 
-@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
-a8 \( ( a'16 ) a \)
+@lilypond[quote,verbatim,ragged-right]
+\relative { a'8 \( ( a'16 ) a \) }
 @end lilypond
 
 @cindex PhrasingSlur, example of overriding
@@ -3099,9 +3234,9 @@ centre line and the right end to 4.5 above, and LilyPond will
 select the phrasing slur from the candidates it has found with its
 end points closest to these:
 
-@lilypond[quote,verbatim,fragment,ragged-right,relative=2]
+@lilypond[quote,verbatim,fragment,ragged-right]
 \once \override PhrasingSlur.positions = #'(2.5 . 4.5)
-a8 \( ( a'16 ) a \)
+a'8 \( ( a''16 ) a'' \)
 @end lilypond
 
 This is an improvement, but why not lower the right end of the slur
@@ -3115,18 +3250,26 @@ do this, see @ruser{Modifying ties and slurs}.
 Here's a further example.  We see that the beams
 collide with the ties:
 
-@lilypond[quote,verbatim,fragment,ragged-right]
+@lilypond[quote,verbatim,ragged-right]
 {
   \time 4/2
   <<
-    { c'1 ~ c'2. e'8 f' }
+    \relative { c'1~ 2. e8 f }
     \\
-    { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
+    \relative {
+      e''8 e e e
+      e e e e
+      f2 g
+    }
   >>
   <<
-    { c'1 ~ c'2. e'8 f' }
+    \relative { c'1~ 2. e8 f }
     \\
-    { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
+    \relative {
+      e''8 e e e
+      e e e e
+      f2 g
+    }
   >>
 }
 @end lilypond
@@ -3139,29 +3282,37 @@ say, 1:
 @cindex Beam, example of overriding
 @cindex positions property, example
 
-@lilypond[quote,verbatim,fragment,ragged-right]
+@lilypond[quote,verbatim,ragged-right]
 {
   \time 4/2
   <<
-    { c'1 ~ c'2. e'8 f' }
+    \relative { c'1~ 2. e8 f }
     \\
-    {
+    \relative {
       \override Beam.positions = #'(-1 . -1)
-      e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g''
+      e''8 e e e
+      e e e e
+      f2 g
     }
   >>
   <<
-    { c'1 ~ c'2. e'8 f' }
+    \relative { c'1~ 2. e8 f }
     \\
-    { e''8 e'' e'' e''  e'' e'' e'' e''  f''2 g'' }
+    \relative {
+      e''8 e e e
+      e e e e
+      f2 g
+      \revert Beam.positions
+    }
   >>
 }
 @end lilypond
 
 @noindent
-Note that the override continues to apply in the first voice of
+Note that the override continues to apply in the second voice of
 the second measure of eighth notes, but not to any of the beams in the
-second voice.
+first voice, even those in the later second measure.  As soon as the
+override should no longer apply it should be reverted, as shown.
 
 @node The force-hshift property
 @unnumberedsubsubsec The @code{force-hshift} property
@@ -3171,10 +3322,10 @@ example introduced at the end of @ref{I'm hearing Voices}, which
 was left looking like this:
 
 @lilypond[quote,verbatim,fragment,ragged-right]
-\new Staff \relative c'' {
+\new Staff \relative {
   \key aes \major
   <<
-    { c2 aes4. bes8 }
+    { c''2 aes4. bes8 }
     \\
     { <ees, c>2 des }
     \\
@@ -3188,14 +3339,17 @@ was left looking like this:
 @noindent
 The inner note of the first chord (i.e. the A-flat in the fourth
 Voice) need not be shifted away from the note column of the higher
-note.  To correct this we set @code{force-hshift}, which is a property
-of @code{NoteColumn}, of this note to zero.
+note, so we use @code{\shiftOff}.
 
-In the second chord we prefer the F to line up with the A-flat and the
-lowest note to be positioned slightly right to avoid a collision of
-stems.  We achieve this by setting @code{force-hshift} in the
+In the second chord we prefer the F to line up with the A-flat and
+the lowest note to be positioned slightly right to avoid a collision
+of stems.  We achieve this by setting @code{force-hshift} in the
 @code{NoteColumn} of the low D-flat to move it to the right by half
-a staff-space.
+a staff-space, and setting @code{force-hshift} for the F to zero.
+Note that we use @code{\once} to avoid the settings propagating
+beyond the immediate musical moment, although in this small example
+the @code{\once} and the second @code{\override} in Voice four could
+be omitted.  This would not be good practice.
 
 Here's the final result:
 
@@ -3203,22 +3357,15 @@ Here's the final result:
 @cindex force-hshift property, example
 
 @lilypond[quote,verbatim,fragment,ragged-right]
-\new Staff \relative c'' {
+\new Staff \relative {
   \key aes \major
   <<
-    { c2 aes4. bes8 }
+    { c''2 aes4. bes8 }
     \\
-    {
-      <ees, c>2
-      \once \override NoteColumn.force-hshift = #0.5
-      des2
-    }
+    { <ees, c>2 \once \override NoteColumn.force-hshift = 0.5 des }
     \\
     \\
-    {
-      \override NoteColumn.force-hshift = #0
-      aes'2 f4 fes
-    }
+    { \once \shiftOff aes'2 \once \shiftOff f4 fes }
   >> |
   <c ees aes c>1 |
 }
@@ -3246,16 +3393,16 @@ dynamics, fingering and pedalling.
 @c This example should not be indexed
 @c line-width ensures no break
 @lilypond[quote,ragged-right,line-width=6\in]
-rhMusic = \relative c'' {
+rhMusic = \relative {
   \new Voice {
-    r2 c4.\( g8 |
+    r2 c''4.\( g8 |
     \once \override Tie.staff-position = #3.5
     bes1~ |
     \bar "||"
     \time 6/4
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     <<
       { c,8 d fis bes a }
       \new Voice {
@@ -3288,8 +3435,8 @@ rhMusic = \relative c'' {
   }
 }
 
-lhMusic = \relative c' {
-  r2 <c g ees>2( |
+lhMusic = \relative {
+  r2 <c' g ees>2( |
   <d g, d>1)\arpeggio |
   r2. d,,4 r4 r |
   r4
@@ -3329,9 +3476,9 @@ produces by default:
 
 @c line-width ensures no break
 @lilypond[quote,verbatim,ragged-right,line-width=6\in]
-rhMusic = \relative c'' {
+rhMusic = \relative {
   \new Voice {
-    r2 c4. g8 |
+    r2 c''4. g8 |
     bes1~ |
     \time 6/4
     bes2. r8
@@ -3340,7 +3487,7 @@ rhMusic = \relative c'' {
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
@@ -3355,8 +3502,8 @@ rhMusic = \relative c'' {
   }
 }
 
-lhMusic = \relative c' {
-  r2 <c g ees>2 |
+lhMusic = \relative {
+  r2 <c' g ees>2 |
   <d g, d>1 |
   r2. d,,4 r4 r |
   r4
@@ -3386,9 +3533,9 @@ since these were all covered in the Tutorial.  Doing this gives:
 
 @c line-width ensures no break
 @lilypond[quote,verbatim,ragged-right,line-width=6\in]
-rhMusic = \relative c'' {
+rhMusic = \relative {
   \new Voice {
-    r2 c4.\( g8 |
+    r2 c''4.\( g8 |
     bes1~ |
     \time 6/4
     bes2. r8
@@ -3397,7 +3544,7 @@ rhMusic = \relative c'' {
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
@@ -3412,8 +3559,8 @@ rhMusic = \relative c'' {
   }
 }
 
-lhMusic = \relative c' {
-  r2 <c g ees>2( |
+lhMusic = \relative {
+  r2 <c' g ees>2( |
   <d g, d>1) |
   r2. d,,4 r4 r |
   r4
@@ -3456,9 +3603,9 @@ This completes bar two, giving:
 
 @c line-width ensures no break
 @lilypond[quote,verbatim,ragged-right,line-width=6\in]
-rhMusic = \relative c'' {
+rhMusic = \relative {
   \new Voice {
-    r2 c4.\( g8 |
+    r2 c''4.\( g8 |
     \once \override Tie.staff-position = #3.5
     bes1~ |
     \bar "||"
@@ -3469,7 +3616,7 @@ rhMusic = \relative c'' {
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
@@ -3484,8 +3631,8 @@ rhMusic = \relative c'' {
   }
 }
 
-lhMusic = \relative c' {
-  r2 <c g ees>2( |
+lhMusic = \relative {
+  r2 <c' g ees>2( |
   <d g, d>1)\arpeggio |
   r2. d,,4 r4 r |
   r4
@@ -3507,8 +3654,8 @@ lhMusic = \relative c' {
 @end lilypond
 
 On to bar three and the start of the Moderato section.  The tutorial
-showed how to add bold text with the @code{\markup} command, so
-adding @qq{Moderato} in bold is easy.  But how do we merge notes in
+showed how to add a tempo indication with the @code{\tempo} command, so
+adding @qq{Moderato} is easy.  But how do we merge notes in
 different voices together?  This is where we need to turn again to
 the Notation Reference for help.  A search for @qq{merge} in the
 Notation Reference index quickly leads us to the commands for merging
@@ -3535,14 +3682,14 @@ to the end, giving:
 
 @c line-width ensures no break
 @lilypond[quote,ragged-right,line-width=6\in]
-rhMusic = \relative c'' {
+rhMusic = \relative {
   \new Voice {
-    r2 c4.\( g8 |
+    r2 c''4.\( g8 |
     \once \override Tie.staff-position = #3.5
     bes1~ |
     \bar "||"
     \time 6/4
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
     % Start polyphonic section of four voices
@@ -3550,7 +3697,7 @@ rhMusic = \relative c'' {
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
@@ -3567,8 +3714,8 @@ rhMusic = \relative c'' {
   }
 }
 
-lhMusic = \relative c' {
-  r2 <c g ees>2( |
+lhMusic = \relative {
+  r2 <c' g ees>2( |
   <d g, d>1)\arpeggio |
   r2. d,,4 r4 r |
   r4
@@ -3609,14 +3756,14 @@ Applying these changes gives:
 
 @c line-width ensures no break
 @lilypond[quote,verbatim,ragged-right,line-width=6\in]
-rhMusic = \relative c'' {
+rhMusic = \relative {
   \new Voice {
-    r2 c4.\( g8 |
+    r2 c''4.\( g8 |
     \once \override Tie.staff-position = #3.5
     bes1~ |
     \bar "||"
     \time 6/4
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
     % Start polyphonic section of four voices
@@ -3644,8 +3791,8 @@ rhMusic = \relative c'' {
   }
 }
 
-lhMusic = \relative c' {
-  r2 <c g ees>2( |
+lhMusic = \relative {
+  r2 <c' g ees>2( |
   <d g, d>1)\arpeggio |
   r2. d,,4 r4 r |
   r4
@@ -3679,14 +3826,14 @@ the @code{force-hshift} property.  Here's the final result:
 
 @c line-width ensures no break
 @lilypond[quote,verbatim,ragged-right,line-width=6\in]
-rhMusic = \relative c'' {
+rhMusic = \relative {
   \new Voice {
-    r2 c4.\( g8 |
+    r2 c''4.\( g8 |
     \once \override Tie.staff-position = #3.5
     bes1~ |
     \bar "||"
     \time 6/4
-    bes2.^\markup { \bold "Moderato" } r8
+    bes2.\tempo "Moderato" r8
     \mergeDifferentlyHeadedOn
     \mergeDifferentlyDottedOn
     % Start polyphonic section of four voices
@@ -3722,8 +3869,8 @@ rhMusic = \relative c'' {
   }
 }
 
-lhMusic = \relative c' {
-  r2 <c g ees>2( |
+lhMusic = \relative {
+  r2 <c' g ees>2( |
   <d g, d>1)\arpeggio |
   r2. d,,4 r4 r |
   r4
@@ -3764,91 +3911,50 @@ lhMusic = \relative c' {
 * Simulating a fermata in MIDI::
 @end menu
 
-@cindex transparent property, use of
-@cindex objects, making invisible
 @cindex removing objects
 @cindex objects, removing
-@cindex hiding objects
-@cindex objects, hiding
-@cindex invisible objects
-@cindex objects, invisible
 
 @node Tying notes across voices
 @unnumberedsubsubsec Tying notes across voices
 
 @cindex tying notes across voices
 
-The following example demonstrates how to connect notes in
-different voices using ties.  Normally, only two notes in the
-same voice can be connected with ties.  By using two voices,
-with the tied notes in one of them
+The following example demonstrates how to connect notes in different
+voices using ties.  Normally, only notes in the same voice can be
+connected with ties.  By using two voices, with the tied notes in one
+of them
 
-@lilypond[quote,fragment,relative=2]
-<< { b8~ b\noBeam } \\ { b8[ g] } >>
+@lilypond[quote]
+<< { b'8~ 8\noBeam } \\ { b'8[ g'] } >>
 @end lilypond
 
 @noindent
-and blanking the first up-stem in that voice, the tie appears to
-cross voices:
-
-@cindex Stem, example of overriding
-@cindex transparent property, example
+and removing the first up-stem and its flag in that voice, the tie
+appears to cross voices:
 
-@lilypond[quote,fragment,relative=2,verbatim]
-<<
-  {
-    \tweak Stem.transparent ##t
-    b8~ b\noBeam
-  }
-\\
-  { b8[ g] }
->>
-@end lilypond
-
-To make sure that the just-blanked stem doesn't squeeze the tie
-too much, we can lengthen the stem by setting the
-@code{length} to @code{8},
+@funindex \omit
+@cindex Stem, example of removing
+@cindex Flag, example of removing
+@cindex @code{\omit}, example
+@cindex example of @code{\omit}
 
-@lilypond[quote,fragment,relative=2,verbatim]
+@lilypond[quote,verbatim]
 <<
   {
-    \tweak Stem.transparent ##t
-    \tweak Stem.length #8
-    b8~ b\noBeam
+    \once \omit Stem
+    \once \omit Flag
+    b'8~ 8\noBeam
   }
 \\
-  { b8[ g] }
+  { b'8[ g'] }
 >>
 @end lilypond
 
-@funindex \single
-@cindex tweak, generated from override
-Now for @emph{overriding} the transparency of a graphical object,
-we could have used the shorthand @code{\hide} as explained above.
-Tweaking is a different operation, affecting only properties
-generated from a single music expression.  It turns out that we
-can convert overrides into tweaks using @code{\single}, making it
-possible to rewrite the above example as
-
-@lilypond[quote,fragment,relative=2,verbatim]
-<<
-  {
-    \single \hide Stem
-    \single \hide Flag
-    \tweak Stem.length #8
-    b8~ b\noBeam
-  }
-\\
-  { b8[ g] }
->>
-@end lilypond
+@seealso
+Learning Manual:
+@ref{The once prefix,,The @code{@bs{}once} prefix},
+@ref{The stencil property}.
 
-In this particular case, the difference to @code{\once \hide} is
-not apparent.  It is important when there are several objects at
-the same point in musical time (like noteheads in a chord).  In
-that case, @code{\once} will affect all of those objects while
-@code{\single} will only affect a single one, the one generated by
-the immediately following music expression.
 
 @node Simulating a fermata in MIDI
 @unnumberedsubsubsec Simulating a fermata in MIDI
@@ -3877,10 +3983,10 @@ We show here the effect of the two methods:
 
 @lilypond[quote,verbatim,ragged-right]
 \score {
-  \relative c'' {
+  \relative {
     % Visible tempo marking
     \tempo 4=120
-    a4 a a
+    a'4 a a
     \once \hide Score.MetronomeMark
     % Invisible tempo marking to lengthen fermata in MIDI
     \tempo 4=80
@@ -3899,10 +4005,10 @@ We show here the effect of the two methods:
 
 @lilypond[quote,verbatim,ragged-right]
 \score {
-  \relative c'' {
+  \relative {
     % Visible tempo marking
     \tempo 4=120
-    a4 a a
+    a'4 a a
     \once \omit Score.MetronomeMark
     % Invisible tempo marking to lengthen fermata in MIDI
     \tempo 4=80
@@ -3981,10 +4087,10 @@ normal = {
 
 global = { \key c \major \time 4/4 \partial 4 }
 
-SopranoMusic = \relative c' { c4 | e4. e8 g4 g    | a4   a   g  }
-AltoMusic    = \relative c' { c4 | c4. c8 e4 e    | f4   f   e  }
-TenorMusic   = \relative c  { e4 | g4. g8 c4.  b8 | a8 b c d e4 }
-BassMusic    = \relative c  { c4 | c4. c8 c4 c    | f8 g a b c4 }
+SopranoMusic = \relative { c'4 | e4. e8 g4 g    | a4   a   g  }
+AltoMusic    = \relative { c'4 | c4. c8 e4 e    | f4   f   e  }
+TenorMusic   = \relative  { e4 | g4. g8 c4.  b8 | a8 b c d e4 }
+BassMusic    = \relative  { c4 | c4. c8 c4 c    | f8 g a b c4 }
 
 VerseOne = \lyrics {
   E -- | ter -- nal \emphasize Fa -- ther, | \normal strong to save,
@@ -4044,13 +4150,13 @@ mpdolce =
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #{ <>^\markup \bold \box #string #})
 
-\relative c'' {
+\relative {
   \tempo 4=50
-  a4.\mpdolce d8 cis4--\glissando a |
+  a'4.\mpdolce d8 cis4--\glissando a |
   b4 bes a2 |
   \inst "Clarinet"
   cis4.\< d8 e4 fis |
@@ -4074,7 +4180,7 @@ mpdolce =
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #@{ <>^\markup \bold \box #string #@})
 @end example
@@ -4091,9 +4197,9 @@ Now let's modify our music (let's save this file as @file{music.ly}).
 @example
 \include "definitions.ily"
 
-\relative c'' @{
+\relative @{
   \tempo 4=50
-  a4.\mpdolce d8 cis4--\glissando a |
+  a'4.\mpdolce d8 cis4--\glissando a |
   b4 bes a2 |
   \inst "Clarinet"
   cis4.\< d8 e4 fis |
@@ -4109,13 +4215,13 @@ mpdolce =
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #{ <>^\markup \bold \box #string #})
 
-\relative c'' {
+\relative {
   \tempo 4=50
-  a4.\mpdolce d8 cis4--\glissando a |
+  a'4.\mpdolce d8 cis4--\glissando a |
   b4 bes a2 |
   \inst "Clarinet"
   cis4.\< d8 e4 fis |
@@ -4141,7 +4247,7 @@ mpdolce =
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #@{ <>^\markup \bold \box #string #@})
 
@@ -4171,7 +4277,7 @@ mpdolce =
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #{ <>^\markup \bold \box #string #})
 
@@ -4192,9 +4298,9 @@ inst =
   }
 }
 
-\relative c'' {
+\relative {
   \tempo 4=50
-  a4.\mpdolce d8 cis4--\glissando a |
+  a'4.\mpdolce d8 cis4--\glissando a |
   b4 bes a2 |
   \inst "Clarinet"
   cis4.\< d8 e4 fis |
@@ -4219,7 +4325,7 @@ mpdolce =
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #@{ <>^\markup \bold \box #string #@})
 
@@ -4250,7 +4356,7 @@ mpdolce =
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #{ <>^\markup \bold \box #string #})
 
@@ -4267,9 +4373,9 @@ inst =
   }
 }
 
-\relative c'' {
+\relative {
   \tempo 4=50
-  a4.\mpdolce d8 cis4--\glissando a |
+  a'4.\mpdolce d8 cis4--\glissando a |
   b4 bes a2 |
   \inst "Clarinet"
   cis4.\< d8 e4 fis |
@@ -4377,10 +4483,10 @@ Let's begin by looking at some files in @file{ly/}.
 Open @file{ly/property-init.ly} in a text editor.  The one
 you normally use for @code{.ly} files will be fine.  This file
 contains the definitions of all the standard LilyPond predefined
-commands, such as @code{\stemUp} and @code{\slurDotted}.  You will
+commands, such as @code{\tieUp} and @code{\slurDotted}.  You will
 see that these are nothing more than definitions of variables
 containing one or a group of @code{\override} commands.  For
-example, @code{/tieDotted} is defined to be:
+example, @code{\tieDotted} is defined to be:
 
 @example
 tieDotted = @{
@@ -4484,7 +4590,7 @@ the staff.
        ((0) (x11-color 'violet ))  ; for B
        )))
 
-\relative c' {
+\relative {
   % Arrange to obtain color from color-notehead procedure
   \override NoteHead.color = #color-notehead
   a2 b | c2 d | e2 f | g2 a |