Doc: NR 5.3 Add \single command

Documentation/learning/tweaks.itely

 @c -*- coding: utf-8; mode: texinfo; -*-
 
 @ignore
     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
 
     When revising a translation, copy the HEAD committish of the
     version that you are working on.  For details, see the Contributors'
     Guide, node Updating translation committishes..
 @end ignore
 
-@c \version "2.17.6"
+@c \version "2.19.22"
 
 @node Tweaking output
 @chapter Tweaking output
 
 This chapter discusses how to modify output.  LilyPond is extremely
 configurable; virtually every fragment of output may be changed.
 
 
 @menu
 * Tweaking basics::
 * The Internals Reference manual::
 * Appearance of objects::
 * Placement of objects::
+* Vertical spacing::
 * Collisions of objects::
 * Further tweaking::
 @end menu
 
 @node Tweaking basics
 @section Tweaking basics
 
 @menu
 * Introduction to tweaks::
 * Objects and interfaces::
@@ skipping 63 matching lines @@
 are still objects in the generic sense above, and so they too all have
 properties associated with them, such as their position, size, color,
 etc.
 
 Some layout objects are still more specialized.  Phrasing slurs,
 crescendo hairpins, ottava marks, and many other grobs are not
 localized in a single place -- they have a starting point, an
 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
 size, a position, etc, and all these properties are processed in the
 same way during LilyPond's interpretation of the input file.  To
 simplify these internal operations these common actions and properties
 are grouped together in an object called a @code{grob-interface}.
 There are many other groupings of common properties like this, each
 one given a name ending in @code{interface}.  In total there are over
@@ skipping 48 matching lines @@
 modified by different commands, so it is useful to be able to recognize
 the types of objects and properties from their names.
 
 
 @node Tweaking methods
 @subsection Tweaking methods
 
 @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
 
 @funindex \override
 @funindex override
 
 We have already met the commands @code{\set} and @code{\with}, used to
 change the properties of @strong{contexts} and to remove and add
 @strong{engravers}, in @ref{Modifying context properties}, and
@@ skipping 41 matching lines @@
 Scheme mode, see @rextend{LilyPond Scheme syntax}.
 
 @code{\override} is the most common command used in tweaking, and
 most of the rest of this chapter will be directed to presenting
 examples of how it is used.  Here is a simple example to change the
 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 |
-@end lilypond
-
-
-@node The \revert command
-@unnumberedsubsubsec The @code{\revert} command
+@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{@bs{}revert} command
 
 @cindex revert command
 
 @funindex \revert
 @funindex revert
 
 Once overridden, the property retains its new value until it is
 overridden again or a @code{\revert} command is encountered.
 The @code{\revert} command has the following syntax and causes
 the value of the property to revert to its original default
 value; note, not its previous value if several @code{\override}
 commands have been issued.
 
 @example
 \revert @var{Context}.@var{LayoutObject}.@var{layout-property}
 @end example
 
 Again, just like @var{Context} in the @code{\override} command,
 @var{Context} is often not needed.  It will be omitted
 in many of the following examples.  Here we revert the color
 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 |
-@end lilypond
-
-
-@node The \once prefix
-@unnumberedsubsubsec The @code{\once} prefix
+@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{@bs{}once} prefix
 
 @funindex \once
 @funindex once
 
-Both the @code{\override} and the @code{\set} commands may be prefixed
-by @code{\once}.  This causes the following @code{\override} or
-@code{\set} command to be effective only during the current musical
+@code{\override}, @code{\revert}. @code{\set}, and @code{\unset}
+commands may be prefixed with @code{\once}.  This causes such a
+command to be effective only during the current musical
 moment before the property reverts back to its previous value (this can
 be different from the default if another @code{\override} is still in
 effect).  Using the same example, we can change the color of a single
 note like this:
 
 @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 |
-\once \override NoteHead.color = #green
-g4 a
-\revert NoteHead.color
-b c |
-@end lilypond
-
-
-@node The \overrideProperty command
-@unnumberedsubsubsec The @code{\overrideProperty} command
+@lilypond[quote,verbatim]
+\relative {
+  c'4 d
+  \override NoteHead.color = #red
+  e4 f |
+  \once \override NoteHead.color = #green
+  g4 a
+  \once \revert NoteHead.color
+  b c |
+  \revert NoteHead.color
+  f2 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 {
+  c'4( d)
+  \once \slurDashed
+  e4( f) |
+  g4( a)
+  \once \hideNotes
+  b( c) |
+}
+@end lilypond
+
+@node The overrideProperty command
+@unnumberedsubsubsec The @code{@bs{}overrideProperty} command
 
 @cindex overrideProperty command
 
 @funindex \overrideProperty
 @funindex overrideProperty
 
 There is another form of the override command,
 @code{\overrideProperty}, which is occasionally required.
 We mention it here for completeness, but for details see
 @rextend{Difficult tweaks}.
 @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
 
 @funindex \tweak
 @funindex tweak
 
 The final tweaking command which is available is @code{\tweak}.  This
 should be used when several objects occur at the same musical moment,
 but you only want to change the properties of selected ones, such as a
 single note within a chord.  Using @code{\override} would affect all the
 notes within a chord, whereas @code{\tweak} affects just the following
 item in the input stream.
 
 Here's an example.  Suppose we wish to change the size of the
 middle note head (the E) in a C major chord.  Let's first see what
 @code{\once \override} would do:
 
 @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.
 This is because all the notes of a chord occur at the same
 @emph{musical moment}, and the action of @code{\once} is to
 apply the override to all layout objects of the type specified
 which occur at the same musical moment as the @code{\override}
 command itself.
 
 The @code{\tweak} command operates in a different way.  It acts on
 the immediately following item in the input stream.  In its simplest
 form, it is effective only on objects which are created directly
 from the following item, essentially note heads and articulations.
 
 So to return to our example, the size of the middle note of
 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
 @code{\override} command.  The context should not be specified; in
 fact, it would generate an error to do so.  Both context and layout
 object are implied by the following item in the input stream.  Note
 also that an equals sign should not be present.  So the simple form
 of the @code{\tweak} command is
 
 @example
 \tweak @var{layout-property} #@var{value}
 @end example
 
 A @code{\tweak} command can also be used to modify just one in
 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
 
 @noindent
 Note that the @code{\tweak} command must be preceded by an articulation
 mark since the tweaked expression needs to be applied as an articulation
 itself.  In case of multiple direction overrides (@code{^} or @code{_}),
 the leftmost override wins since it is applied last.
 
 @cindex @code{\tweak}, Accidental
 @cindex @code{\tweak}, specific layout object
 
 Objects such as stems and accidentals are created later, and not
 directly from the following event.  It is still possible to use
 @code{\tweak} on such indirectly created objects by explicitly naming
 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
 @cindex triplets, nested
 @cindex bracket, tuplet
 @cindex bracket, triplet
 @cindex tuplet bracket
 @cindex triplet bracket
 
 @funindex TupletBracket
 
 The @code{\tweak} command must also be used to change the
 appearance of one of a set of nested tuplets which begin at the
 same musical moment.  In the following example, the long tuplet
 bracket and the first of the three short brackets begin at the
 same musical moment, so any @code{\override} command would apply
 to both of them.  In the example, @code{\tweak} is used to
 distinguish between them.  The first @code{\tweak} command
 specifies that the long tuplet bracket is to be placed above the
 notes and the second one specifies that the tuplet number is to be
 printed in red on the first short tuplet bracket.
 
 @cindex @code{\tweak}, example
 @cindex direction property, example
 @cindex color property, example
 
-@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
-\tweak direction #up
-\times 4/3 {
-  \tweak color #red
-  \times 2/3 { c8[ c c] }
-  \times 2/3 { c8[ c c] }
-  \times 2/3 { 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
 
 If nested tuplets do not begin at the same moment, their
 appearance may be modified in the usual way with
 @code{\override} commands:
 
 @cindex text property, example
 @cindex tuplet-number function, example
 @cindex transparent property, example
 @cindex TupletNumber, example of overriding
 
-@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
-\times 2/3 { c8[ c c] }
-\once \override TupletNumber.text = #tuplet-number::calc-fraction-text
-\times 2/3 {
-  c8[ c]
-  c8[ c]
-  \once \override TupletNumber.transparent = ##t
-  \times 2/3 { c8[ c c] }
-  \times 2/3 { 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
 
 
 @seealso
 Notation Reference:
 @ruser{Tweak and single}.
+
+@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
 
 @cindex Internals Reference
 
 @menu
 * Properties of layout objects::
 * Properties found in interfaces::
@@ skipping 31 matching lines @@
 
 @cindex override example
 @cindex Internals Reference, example of using
 @cindex @code{\addlyrics} example
 
 Let's use a concrete example with a simple fragment of real
 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
   }
   \addlyrics {
     The man who | feels love's sweet e -- | mo -- tion
   }
 }
 @end lilypond
 
 Suppose now that we decide we would like the slurs to be a
@@ skipping 59 matching lines @@
 Don't forget the@tie{}@code{#} preceding the new value!
 
 The final question is, @q{Where should this command be
 placed?}  While you are unsure and learning, the best
 answer is, @q{Within the music, before the first slur and
 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
   }
   \addlyrics {
     The man who | feels love's sweet e -- | mo -- tion
   }
 }
 @end lilypond
 
 @noindent
@@ skipping 41 matching lines @@
 the @code{\override} command it causes it to change only the slur
 which begins on the @strong{immediately following} note.  If the
 immediately following note does not begin a slur the command has no
 effect at all -- it is not remembered until a slur is encountered, it
 is simply discarded.  So the command with @code{\once} must be
 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 |
     g8[( es]) es d[( f]) as |
     as8 g
   }
   \addlyrics {
     The man who | feels love's sweet e -- | mo -- tion
   }
 }
@@ skipping 14 matching lines @@
 @funindex revert
 
 Finally, what if we wanted just the first two slurs to be
 heavier?  Well, we could use two commands, each preceded by
 @code{\once} placed immediately before each of the notes where
 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 |
     % Increase thickness of immediately following slur only
     \once \override Slur.thickness = #5.0
     g8[( es]) es d[( f]) as |
     as8 g
   }
   \addlyrics {
     The man who | feels love's sweet e -- | mo -- tion
   }
 }
 @end lilypond
 
 @noindent
 or we could omit the @code{\once} command and use the @code{\revert}
 command to return the @code{thickness} property to its default value
 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 |
     g8[( es]) es
     % Revert thickness of all following slurs to default of 1.2
     \revert Slur.thickness
     d8[( f]) as |
     as8 g
   }
   \addlyrics {
@@ skipping 81 matching lines @@
 
 @noindent
 This should be placed just in front of the lyrics we wish to affect,
 like so:
 
 @cindex font-shape property, example
 @cindex italic, example
 @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
   }
   \addlyrics {
     \override LyricText.font-shape = #'italic
     The man who | feels love's sweet e -- | mo -- tion
   }
 }
 @end lilypond
 
@@ skipping 144 matching lines @@
 
 This property controls the appearance of the bar lines by specifying
 the symbol (glyph) which should be printed.  In common
 with many other properties, it can be set to print nothing by
 setting its value to @code{#f}.  Let's try it, as before, omitting
 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
 }
 @end lilypond
 
 The bar lines are still printed.  What is wrong?  Go back to the IR
 and look again at the page giving the properties of BarLine.  At the
 top of the page it says @qq{Barline objects are created by:
 Bar_engraver}.  Go to the @code{Bar_engraver} page.  At the bottom it
 gives a list of Contexts in which the bar engraver operates.  All of
 them are of the type @code{Staff}, so the reason the @code{\override}
 command failed to work as expected is because @code{Barline} is not in
 the default @code{Voice} context.  If the context is specified
 incorrectly, the command simply does not work.  No error message is
 produced, and nothing is logged in the log file.  Let's try correcting
 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
 }
 @end lilypond
 
 Now the bar lines have vanished.  Setting the @code{stencil}
 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
 }
 @end lilypond
 
 Note, though, that setting the @code{stencil} property to @code{#f}
 will cause errors when the dimensions of the object are required for
 correct processing.  For example, errors will be generated if the
 @code{stencil} property of the @code{NoteHead} object is set to
 @code{#f}.  If this is the case, you can instead use the
-@code{point-stencil} function, which sets the stencil to a object
+@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
 }
 @end lilypond
 
 @node The break-visibility property
 @unnumberedsubsubsec The @code{break-visibility} property
 
 @cindex break-visibility property
 
 We see from the @code{BarLine} properties in the IR that the
 @code{break-visibility} property requires a vector of three booleans.
 These control respectively whether bar lines are printed at the end of
 a line, in the middle of lines, and at the beginning of lines.  For
 our example we want all bar lines to be suppressed, so the value we
 need is @code{#(#f #f #f)} (also available
 under the name @code{all-invisible}).  Let's try that, remembering to include
 the @code{Staff} context.  Note also that in writing this value we
 have @code{##} before the opening parenthesis.  One @code{#} is required
 as part of vector constant syntax, and the first@tie{}@code{#} is
 required, as always, to precede the value itself in the
 @code{\override} command.
 
 @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
 }
 @end lilypond
 
 And we see this too removes all the bar lines.
 
 @node The transparent property
 @unnumberedsubsubsec The @code{transparent} property
 
 @cindex transparent property
 @cindex transparency
 
 We see from the properties specified in the @code{grob-interface} page
 in the IR that the @code{transparent} property is a boolean.  This
 should be set to @code{#t} to make the grob transparent.  In this next
 example let us make the time signature invisible rather than the bar
 lines.  To do this we need to find the grob name for the time
 signature.  Back to the @q{All layout objects} page in the IR to find
 the properties of the @code{TimeSignature} layout object.  This is
 produced by the @code{Time_signature_engraver} which you can check
 also lives in the @code{Staff} context and also supports the
 @code{grob-interface}.  So the command to make the time signature
 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
 }
 @end lilypond
 
 @noindent
 Again, setting the @code{transparent} property is a rather
 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
 }
 @end lilypond
 
 @noindent
 In either case, the time signature is gone, but this command
 leaves a gap where
 the time signature should be.  Maybe this is what is wanted for
 an exercise for the student to fill it in, but in other
 circumstances a gap might be undesirable.  To remove it, the
 stencil for the time signature should be set to @code{#f}
 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
 }
 @end lilypond
 
 @noindent
 and the difference is obvious: setting the stencil to @code{#f}
 (possibly via @code{\omit})
 removes the object entirely; making the object @code{transparent}
 (which can be done using @code{\hide})
@@ skipping 19 matching lines @@
 requires is actually a list of values in internal units,
 but, to avoid having to know what these are, several ways
 are provided to specify colors.  The first way is to use one
 of the @q{normal} colors listed in the first table in
 @ruser{List of colors}.  To set the bar lines to white
 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
 }
 @end lilypond
 
 @noindent
 and again, we see the bar lines are not visible.  Note that
 @emph{white} is not preceded by an apostrophe -- it is not
 a symbol, but a @emph{variable}.  When evaluated, it provides
 the list of internal values required to set the color to
 white.  The other colors in the normal list are variables
 too.  To convince yourself this is working you might like
 to change the color to one of the other variables in the
 list.
 
 @cindex color, X11
 @cindex X11 colors
 
 @funindex x11-color
 
 The second way of changing the color is to use the list of
 X11 color names in the second list in @ruser{List of colors}.
 However, these are mapped to the actual values by the function
 @code{x11-color} which
 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
 }
 @end lilypond
 
 @noindent
 Note that in this case the function @code{x11-color} takes
 a symbol as an argument, so the symbol must be preceded by
 an apostrophe to keep it from being evaluated as a variable, and
 the whole function call has to be enclosed in parentheses.
 
 @cindex rgb colors
 @cindex color, rgb
 
 @funindex rgb-color
 
 There is another function, one which converts RGB values into
 internal colors -- the @code{rgb-color} function.  This takes
 three arguments giving the intensities of the red, green and
 blue colors.  These take values in the range 0 to 1.  So to
 set the color to red the value should be @code{(rgb-color 1 0 0)}
 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
 }
 @end lilypond
 
 Finally, there is also a grey scale available as part of the
 X11 set of colors.  These range from black, @code{'grey0},
 to white, @code{'grey100}, in steps of 1.  Let's illustrate
 this by setting all the layout objects in our example to
 various shades of grey:
 
 @cindex StaffSymbol, example of overriding
 @cindex TimeSignature, example of overriding
 @cindex Clef, example of overriding
 @cindex NoteHead, example of overriding
 @cindex Stem, example of overriding
 @cindex BarLine, example of overriding
 @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)
   \override Staff.Clef.color = #(x11-color 'grey60)
   \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
 }
 @end lilypond
 
 @noindent
 Note the contexts associated with each of the layout objects.
 It is important to get these right, or the commands will not
 work!  Remember, the context is the one in which the appropriate
 engraver is placed.  The default context for engravers can be
@@ skipping 11 matching lines @@
 @cindex objects, size of
 @cindex objects, changing size of
 
 Let us begin by looking again at the earlier example
 (see @ref{Nesting music expressions}) which showed
 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 }
       \new Staff \with {
         alignAboveContext = #"main" }
       { f8 f c }
     >>
     r4 |
   }
 }
 @end lilypond
 
 Ossia are normally written without clef and time signature, and
 are usually printed slightly smaller than the main staff.  We
 already know now how to remove the clef and time signature --
 we simply set the stencil of each to @code{#f}, as follows:
 
 @cindex alignAboveContext property, example
 @cindex @code{\with}, example
 @funindex \omit
 @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 }
       \new Staff \with {
         alignAboveContext = #"main"
       }
       {
         \omit Staff.Clef
         \omit Staff.TimeSignature
         { f8 f c }
@@ skipping 39 matching lines @@
 If fact, an error will be generated if a context is specified
 in this location.
 
 So we could replace the example above with
 
 @cindex alignAboveContext property, example
 @cindex @code{\with}, example
 @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 }
       \new Staff \with {
         alignAboveContext = #"main"
         % Don't print clefs in this staff
         \override Clef.stencil = ##f
         % Don't print time signatures in this staff
         \override TimeSignature.stencil = ##f
       }
       { f8 f c }
     >>
     r4 |
   }
 }
 @end lilypond
 
 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 }
       \new Staff \with {
         alignAboveContext = #"main"
         % Don't print clefs in this staff
         \omit Clef
         % Don't print time signatures in this staff
         \omit TimeSignature
       }
@@ skipping 40 matching lines @@
 step reduces or increases the size by approximately 12%.
 
 Let's try it in our ossia example:
 
 @cindex alignAboveContext property, example
 @cindex @code{\with}, example
 @cindex Clef, example of overriding
 @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 }
       \new Staff \with {
         alignAboveContext = #"main"
         \omit Clef
         \omit TimeSignature
         % Reduce all font sizes by ~24%
         fontSize = #-2
       }
@@ skipping 42 matching lines @@
 @cindex alignAboveContext property, example
 @cindex @code{\with}, example
 @cindex Clef, example of overriding
 @cindex TimeSignature, example of overriding
 @cindex fontSize property, example
 @cindex StaffSymbol, example of overriding
 @cindex magstep function, example of using
 @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 }
       \new Staff \with {
         alignAboveContext = #"main"
         \omit Clef
         \omit TimeSignature
         fontSize = #-2
         % Reduce stem length and line spacing to match
         \override StaffSymbol.staff-space = #(magstep -2)
@@ skipping 83 matching lines @@
 @code{outside-staff-priority} the one encountered first will be
 placed closer to the staff.
 
 In the following example all the markup texts have the same
 priority (since it is not explicitly set).  Note that @q{Text3}
 is automatically positioned close to the staff again, nestling
 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
 possible (subject to a minimum separation).  If notes project
 a long way towards an adjacent staff they will force the
 staves further apart only if an overlap of the notation
 would otherwise occur.  The following example demonstrates
 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
 
 
 @node Within-staff objects
 @subsection Within-staff objects
 
 We have already seen how the commands @code{\voiceXXX} affect the
 direction of slurs, ties, fingering and everything else which depends on
@@ skipping 18 matching lines @@
 @end menu
 
 @node The direction property
 @unnumberedsubsubsec The @code{direction} property
 
 @cindex down
 @cindex up
 @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.
-
-@cindex Stem, example of overriding
+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 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 |
-@end lilypond
-
-Here we use the constants @code{DOWN} and @code{UP}.
+@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 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
 simpler equivalent predefined commands available.  Here is a table of
 the commonest.  The meaning of each is stated where it is not obvious.
 
 @multitable @columnfractions .2 .2 .25 .35
 @headitem Down/Left
   @tab Up/Right
   @tab Revert
@@ skipping 30 matching lines @@
   @tab @code{\tieUp}
   @tab @code{\tieNeutral}
   @tab
 @item @code{\tupletDown}
   @tab @code{\tupletUp}
   @tab @code{\tupletNeutral}
   @tab Tuplets are below/above notes
 @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
 
 @cindex fingering, placement
 @cindex fingering, chords
 
 The placement of fingering on single notes can also be controlled
 by the @code{direction} property, but changing @code{direction}
 has no effect on chords.  As we shall see, there are special
 commands which allow the fingering of individual notes
 of chords to be controlled, with the fingering being placed
 above, below, to the left or to the right of each note.
 
 First, here's the effect of @code{direction} on the fingering
 attached to single notes.  The first bar shows the default
 behaviour, and the following two bars shows the effect of
 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
 easiest way of manually setting the fingering above or below
 the notes; using @code{_} or @code{^} instead of @code{-} before
 the fingering number is usually preferable.  Here is the previous
 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
 directional prefixes, @code{_} and @code{^} do work.  By default,
 the fingering is automatically placed both above and below the
 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
 but this may be overridden to manually force all or any of the
 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
 individual notes in a chord is possible by using the
 @code{\set fingeringOrientations} command.  The format of this
 command is:
 
 @example
 @code{\set fingeringOrientations = #'([up] [left/right] [down])}
 @end example
@@ skipping 17 matching lines @@
 @warning{To control the placement of the fingering of a single
 note using this command it is necessary to write it as a single
 note chord by placing angle brackets round it.}
 
 Here are a few examples:
 
 @cindex fingering example
 @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
 If the fingering seems a little crowded the @code{font-size}
 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
 @subsection Outside-staff objects
 
 Outside-staff objects are automatically placed to avoid collisions.
 There are several ways to override the automatic placement if the
 positioning is not optimum.
 
 @menu
 * The outside-staff-priority property::
-* The \textLengthOn command::
+* The textLengthOn command::
 * Dynamics placement::
 * Grob sizing::
 @end menu
 
 
 @node The outside-staff-priority property
 @unnumberedsubsubsec The @code{outside-staff-priority} property
 
 Objects with the lower value of the @code{outside-staff-priority}
 property are placed nearer to the staff, and other outside-staff
@@ skipping 62 matching lines @@
 @cindex ottava bracket
 
 @funindex \startTextSpan
 @funindex startTextSpan
 @funindex \stopTextSpan
 @funindex stopTextSpan
 
 @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 }
 % Place dynamics above staff
 \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 --
 text with extender lines above a section of music.  The
 spanner extends from the @code{\startTextSpan} command to
 the @code{\stopTextSpan} command, and the format of the
 text is defined by the @code{\override TextSpanner} command.
 For more details see @ruser{Text spanners}.
 
 It also shows how ottava brackets are created.
@@ skipping 10 matching lines @@
 overridden.  Suppose we would like the ottava bracket to be placed
 below the text spanner in the example above.  All we need to do is to
 look up the priority of @code{OttavaBracket} in the IR or in the
 tables above, and reduce it to a value lower than that of a
 @code{TextSpanner}, remembering that @code{OttavaBracket} is created
 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 }
 % Place dynamics above staff
 \dynamicUp
 % Place following Ottava Bracket below Text Spanners
 \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,
 metronome marks and rehearsal marks, live by default in the
 @code{Score} context, so be sure to use the correct context
 when these are being overriden.
 
 @cindex slurs and outside-staff-priority
 @cindex slurs and articulations
 @cindex articulations and slurs
 
 Slurs by default are classed as within-staff objects, but
 they often appear above the staff if the notes to
 which they are attached are high on the staff.  This can push
 outside-staff objects such as articulations too high, as the slur
 will be placed first.  The @code{avoid-slur} property of the
 articulation can be set to @code{'inside} to bring the articulation
 inside the slur, but the @code{avoid-slur} property is effective
 only if the @code{outside-staff-priority} is also set to @code{#f}.
 Alternatively, the @code{outside-staff-priority} of the slur
 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
 control the vertical placement of individual objects, although
 the results may not always be desirable.  Suppose we would
 like @qq{Text3} to be placed above @qq{Text4} in the example
 under Automatic behavior, above (see @ref{Automatic behavior}).
 All we need to do is to look up the priority of @code{TextScript}
 in the IR or in the tables above, and increase the priority of
 @qq{Text3} to a higher value:
 
 @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
 above @qq{Text2}, and @qq{Text4} now drops down.  Perhaps this is not
 so good.  What we would really like to do is to position all the
 annotation at the same distance above the staff.  To do this, we
 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
 
 @funindex \textLengthOn
 @funindex textLengthOn
 @funindex \textLengthOff
 @funindex textLengthOff
 
 By default, text produced by markup takes up no horizontal space
 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
-@code{\textLengthOff}.  Remember @code{\once} only works with
-@code{\override}, @code{\set}, @code{\revert} or @code{\unset},
-so cannot be used with @code{\textLengthOn}.
+@code{\textLengthOff}.  Alternatively, @code{\once} may be used
+with @code{\textLengthOn} if the effect is to be limited to just a
+single musical moment.
+The corresponding spacing behavior for rehearsal marks and tempo
+indications is independently controlled with the commands
+@code{\markLengthOn} and @code{\markLengthOff}.
 
 @cindex markup text, allowing collisions
 
 Markup text will also avoid notes which project above the staff.
 If this is not desired, the automatic displacement upwards may
 be turned off by setting the priority to @code{#f}.  Here's an
 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
 @unnumberedsubsubsec Dynamics placement
 
 @cindex tweaking dynamics placement
 @cindex dynamics, tweaking placement
 
 Dynamic markings will normally be positioned beneath the
 staff, but may be positioned above with the @code{\dynamicUp}
 command.  They will be positioned vertically relative to the
 note to which they are attached, and will float below (or above)
 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
 together the automatic placement will avoid collisions
 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 c\mp b\p
+\relative { a'4\f b\mf a\mp b\p }
 @end lilypond
 
 @noindent
 Should a similar situation arise in @q{real} music, it may be
 preferable to space out the notes a little further, so the dynamic
 markings can all fit at the same vertical distance from the staff.  We
 were able to do this for markup text by using the @code{\textLengthOn}
 command, but there is no equivalent command for dynamic marks.  So we
 shall have to work out how to do this using @code{\override} commands.
 
@@ skipping 12 matching lines @@
 numbers, @code{X-extent}, which say where the left and right
 edges are relative to the reference point.  The vertical extent
 is similarly defined by a pair of numbers, @code{Y-extent}.
 These are properties of all grobs which support the
 @code{grob-interface}.
 
 @cindex @code{extra-spacing-width}
 
 By default, outside-staff objects are given a width of zero so
 that they may overlap in the horizontal direction.  This is done
-by the trick of adding infinity to the leftmost extent and
-minus infinity to the rightmost extent by setting the
-@code{extra-spacing-width} to @code{'(+inf.0 . -inf.0)}.  So
-to ensure they do not overlap in the horizontal direction we
-must override this value of @code{extra-spacing-width} to
-@code{'(0 . 0)} so the true width shines through.  This is
-the command to do this for dynamic text:
+by the trick of making the leftmost extent infinity and
+the rightmost extent minus infinity by setting the
+@code{extra-spacing-width} to @code{'(+inf.0 . -inf.0)}.  To
+ensure they do not overlap in the horizontal direction we
+must override this value of @code{extra-spacing-width} to give them
+a little extra spacing.  The units are the space between two staff
+lines, so moving the left edge half a unit to the left and the
+right edge half a unit to the right should do it:
 
 @example
-\override DynamicText.extra-spacing-width = #'(0 . 0)
+\override DynamicText.extra-spacing-width = #'(-0.5 . 0.5)
 @end example
 
 @noindent
 Let's see if this works in our previous example:
 
 @cindex DynamicText, example of overriding
 @cindex extra-spacing-width property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\dynamicUp
-\override DynamicText.extra-spacing-width = #'(0 . 0)
-a4\f b\mf c\mp b\p |
-@end lilypond
-
-@noindent
-Well, it has certainly stopped the dynamic marks being
-displaced, but two problems remain.  The marks should be
-spaced a little further apart and it would be better
-if they were all the same distance from the staff.
-We can solve the first problem easily.  Instead of making
-the @code{extra-spacing-width} zero we could add a little
-more to it.  The units are the space between two staff
-lines, so moving the left edge half a unit to the left and the
-right edge half a unit to the right should do it:
-
-@cindex DynamicText, example of overriding
-@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 c\mp b\p
+\relative { a'4\f b\mf a\mp b\p }
 @end lilypond
 
 @noindent
 This looks better, but maybe we would prefer the dynamic marks
 to be aligned along the same baseline rather than going up and
 down with the notes.  The property to do this is
-@code{staff-padding} which is covered in the following section.
-
+@code{staff-padding} which is covered in the section on collisions
+(see @ref{Collisions of objects}).
+
+
+@node Vertical spacing
+@section Vertical spacing
+
+As a rule, LilyPond's vertical spacing of musical objects is pretty
+good.  Let's see how it does with a simple song, with 2 voices and
+piano accompaniment:
+
+@lilypond[quote,fragment,ragged-right]
+<<
+  \new ChoirStaff
+  <<
+    \new Staff {
+      \new Voice = "music" {
+        b'2 c' c' c'
+      }
+    }
+    \new Lyrics
+    \lyricsto "music" {
+      Here are some lyrics
+    }
+    \new Staff {
+      \clef bass e'2 f e c
+    }
+  >>
+  \new PianoStaff
+  <<
+    \new Staff {
+      g''2 c'' c'' a''
+    }
+    \new Staff {
+      \clef bass e2 f c e
+    }
+  >>
+>>
+@end lilypond
+
+There's nothing wrong with the default vertical spacing.  However, let's
+assume that you're working with a publisher with some specific
+requirements for vertical spacing of staves and lyrics: they want
+the lyrics spaced away from any notes, they want the piano
+accompaniment spaced away from the vocal line and they want the two
+piano staves pushed together tightly.  Let's start with the lyrics.
+
+Lyrics sit within a system, and therefore the commands to space them
+are found in @ruser{Flexible vertical spacing within systems}.  It
+tells us that lyrics are @code{non-staff lines} and therefore the
+command to change their spacing will refer to the @code{nonstaff}
+property.  Spacing them away from the staff to which they relate
+(the top line) will use the @code{relatedstaff} property.  Spacing
+them from the lower line will use the @code{unrelatedstaff} property.
+The vocal parts are part of a @code{VerticalAxisGroup}, so we need to
+adjust its properties.  Let's try it and see if it works.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+<<
+  \new ChoirStaff
+  <<
+    \new Staff {
+      \new Voice = "music" {
+        b'2 c' c' c'
+      }
+    }
+    \new Lyrics \with {
+      \override VerticalAxisGroup.
+        nonstaff-relatedstaff-spacing.padding = #5
+      \override VerticalAxisGroup.
+        nonstaff-unrelatedstaff-spacing.padding = #5
+    }
+    \lyricsto "music" {
+      Here are some lyrics
+    }
+    \new Staff {
+      \clef bass e'2 f e c
+    }
+  >>
+  \new PianoStaff
+  <<
+    \new Staff {
+      g''2 c'' c'' a''
+    }
+    \new Staff {
+      \clef bass e2 f c e
+    }
+  >>
+>>
+@end lilypond
+
+Well - yes it does, but perhaps too well.  When we set the
+@code{padding} to 5, LilyPond adds 5 staff spaces to the distance
+between objects, which is too much for us here.  We'll use 2.
+
+Next, let's move the piano music away from the vocal parts.  The
+vocal music is a @code{ChoirStaff}, so we need to increase the
+spacing between that group of staves and the piano staff below.
+We'll do this by changing the @code{basic-distance} of the
+@code{StaffGrouper}'s @code{staffgroup-staff-spacing}.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+<<
+  \new ChoirStaff \with {
+    \override StaffGrouper.
+      staffgroup-staff-spacing.basic-distance = #15
+  }
+  <<
+    \new Staff {
+      \new Voice = "music" {
+        b'2 c' c' c'
+      }
+    }
+    \new Lyrics \with {
+      \override VerticalAxisGroup.
+        nonstaff-relatedstaff-spacing.padding = #2
+      \override VerticalAxisGroup.
+        nonstaff-unrelatedstaff-spacing.padding = #2
+    }
+    \lyricsto "music" {
+      Here are some lyrics
+    }
+    \new Staff {
+      \clef bass e'2 f e c
+    }
+  >>
+  \new PianoStaff
+  <<
+    \new Staff {
+      g''2 c'' c'' a''
+    }
+    \new Staff {
+      \clef bass e2 f c e
+    }
+  >>
+>>
+@end lilypond
+
+Excellent.  Now just for the last requirement to make the piano staves
+closer together.  To do this, we again alter the properties of the
+@code{StaffGrouper}, but this time we're going to reduce both
+the @code{basic-distance} and the @code{padding}.  We can do this
+as shown below.
+
+@lilypond[quote,fragment,ragged-right,verbatim]
+<<
+  \new ChoirStaff \with {
+    \override StaffGrouper.
+      staffgroup-staff-spacing.basic-distance = #15
+  }
+  <<
+    \new Staff {
+      \new Voice = "music" {
+        b'2 c' c' c'
+      }
+    }
+    \new Lyrics \with {
+      \override VerticalAxisGroup.
+        nonstaff-relatedstaff-spacing.padding = #2
+      \override VerticalAxisGroup.
+        nonstaff-unrelatedstaff-spacing.padding = #2
+    }
+    \lyricsto "music" {
+      Here are some lyrics
+    }
+    \new Staff {
+      \clef bass e'2 f e c
+    }
+  >>
+  \new PianoStaff \with {
+    \override StaffGrouper.staff-staff-spacing = #'(
+                            (basic-distance . 0)
+                            (padding . 0))
+  }
+  <<
+    \new Staff {
+      g''2 c'' c'' a''
+    }
+    \new Staff {
+      \clef bass e2 f c e
+    }
+  >>
+>>
+@end lilypond
+
+That's put them really close together -- but it's what
+the publisher wanted.  They could be moved further
+apart by altering the @code{padding} or @code{basic-distance}
+if wanted.
+
+There are many ways of altering vertical spacing.  A key point
+to remember is that the spacing between objects in a
+@code{StaffGroup} (like @code{GrandStaff} or
+@code{PianoStaff} groups) is controlled by the spacing variables
+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 within systems} for more
+details.
 
 @node Collisions of objects
 @section Collisions of objects
 
 @menu
 * Moving objects::
 * Fixing overlapping notation::
 * Real music example::
 @end menu
 
@@ skipping 67 matching lines @@
 the separation from the note heads and between individual accidentals.
 So only the @code{right-padding} property of the @code{AccidentalPlacement}
 object has any effect on the placement of the accidentals.
 
 The @code{staff-padding} property is closely related to the
 @code{padding} property: @code{padding} controls the minimum amount of
 space between any object which supports the
 @code{side-position-interface} and the nearest other object (generally
 the note or the staff lines); @code{staff-padding} applies only to
 those objects which are always set outside the staff -- it controls
-the minimum amount of space that should be inserted between that
-object and the staff.  Note that @code{staff-padding} has no effect on
-objects which are positioned relative to the note rather than the
+the minimum distance from the staff to the outside-staff object.
+Note that @code{staff-padding} has no effect on
+objects that are positioned relative to the note rather than the
 staff, even though it may be overridden without error for such objects
 -- it is simply ignored.
 
 To discover which padding property is required for the object you wish
 to reposition, you need to return to the IR and look up the object's
 properties.  Be aware that the padding properties might not be located
 in the obvious object, so look in objects that appear to be related.
 
 All padding values are measured in staff spaces.  For most
 objects, this value is set by default to be around 1.0 or less
@@ skipping 40 matching lines @@
 
 @code{staff-position} is a property of the
 @code{staff-symbol-referencer-interface}, which is supported by
 objects which are positioned relative to the staff.  It specifies
 the vertical position of the object relative to the center line
 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
 
 @item
 Finally, when all else fails, objects may be manually repositioned
 relative to the staff center line vertically, or by displacing them by
 any distance to a new position.  The disadvantages are that the
 correct values for the repositioning have to be worked out, often by
 trial and error, for every object individually, and, because the
 movement is done after LilyPond has placed all other objects, the user
@@ skipping 81 matching lines @@
 @cindex fixing overlapping notation
 @cindex overlapping notation
 
 The @code{padding} property can be set to increase
 (or decrease) the distance between symbols that are printed
 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
 
 @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
 context handles a certain object.  Since the @code{MetronomeMark}
 object is handled in the @code{Score} context, property changes in the
 @code{Voice} context will not be noticed.  For more details, see
 @ruser{Modifying properties}.
 
 If the @code{padding} property of an object is increased when that
 object is in a stack of objects being positioned according to
@@ skipping 14 matching lines @@
 stencil with a markup containing the desired symbol(s), like this:
 
 @cindex Accidental, example of overriding
 @cindex text property, example
 @cindex stencil property, example
 @cindex AccidentalPlacement, example of overriding
 @cindex right-padding property, example
 
 @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
   cis4 c
   % This improves the spacing
   \once \override Score.AccidentalPlacement.right-padding = #0.6
   \once \override Accidental.stencil = #ly:text-interface::print
   \once \override Accidental.text = #sesquisharp
   cis4 |
 }
 @end lilypond
 
 @noindent
 This necessarily uses an override for the accidental stencil which
 will not be covered until later.  The stencil type must be a
 procedure, here changed to print the contents of the @code{text}
 property of @code{Accidental}, which itself is set to be a
 sesquisharp sign.  This sign is then moved further away from the
 note head by overriding @code{right-padding}.
 
 @noindent
 
 @node The staff-padding property
 @unnumberedsubsubsec The @code{staff-padding} property
 
 @cindex aligning objects on a baseline
 @cindex objects, aligning on a baseline
 
 @code{staff-padding} can be used to align objects such as dynamics
-along a baseline at a fixed height above the staff, rather than at a
-height dependent on the position of the note to which they are
-attached.  It is not a property of @code{DynamicText} but of
+along a baseline at a fixed distance from the staff, when no other
+notation forces them further from the staff.
+It is not a property of @code{DynamicText} but of
 @code{DynamicLineSpanner}.  This is because the baseline should apply
 equally to @strong{all} dynamics, including those created as extended
 spanners.  So this is the way to align the dynamic marks in the
 example taken from the previous section:
 
 @cindex DynamicText, example of overriding
 @cindex extra-spacing-width property, example
 @cindex DynamicLineSpanner, example of overriding
 @cindex staff-padding property, example
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-\dynamicUp
-% Extend width by 1 unit
-\override DynamicText.extra-spacing-width = #'(-0.5 . 0.5)
-% Align dynamics to a base line 2 units above staff
-\override DynamicLineSpanner.staff-padding = #2
-a4\f b\mf c\mp b\p
+@lilypond[quote,fragment,ragged-right,verbatim]
+\override DynamicLineSpanner.staff-padding = #3
+\relative { a'4\f b\mf a\p b\mp }
 @end lilypond
 
 
 @node The self-alignment-X property
 @unnumberedsubsubsec The @code{self-alignment-X} property
 
-The following example shows how this can resolve the collision
-of a string fingering object with a note's stem by aligning the
+The following example shows how to adjust the position
+of a string fingering object relative to a note's stem by aligning the
 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
 @unnumberedsubsubsec The @code{staff-position} property
 
 @cindex object collision within a staff
 
 Multimeasure rests in one voice can collide with notes in another.
 Since these rests are typeset centered between the bar lines, it
 would require significant effort for LilyPond to figure out which
 other notes might collide with it, since all the current collision
 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 } >>
-@end lilypond
-
-The best solution here is to move the multimeasure rest down, since
-the rest is in voice two.  The default in @code{\voiceTwo} (i.e. in
-the second voice of a @code{<<@{...@} \\ @{...@}>>} construct) is that
-@code{staff-position} is set to -4 for MultiMeasureRest, so we need to
-move it, say, four half-staff spaces down to @w{@code{-8}}.
+@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
+rest is in voice two. The default in @code{\voiceTwo} (i.e. in the
+second voice of a @code{<<@{@dots{}@} \\ @{@dots{}@}>>} construct) is
+that @code{staff-position} is set to -4 for MultiMeasureRest, so we need
+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 }
 >>
 @end lilypond
 
 This is better than using, for example, @code{extra-offset},
 because the ledger line above the rest is inserted automatically.
 
 @node The extra-offset property
 @unnumberedsubsubsec The @code{extra-offset} property
 
 @cindex positioning objects
 @cindex positioning grobs
 @cindex objects, positioning
 @cindex grobs, positioning
 
 The @code{extra-offset} property provides complete control over the
 positioning of an object both horizontally and vertically.
 
 In the following example, the second fingering is moved a little to
 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
 
 
 @node The positions property
 @unnumberedsubsubsec The @code{positions} property
 
 @cindex controlling tuplets, slurs, phrasing slurs, and beams manually
 @cindex manually controlling tuplets, slurs, phrasing slurs, and beams
 @cindex tuplet beams, controlling manually
 @cindex slurs, controlling manually
 @cindex phrasing slurs, controlling manually
 @cindex beams, controlling manually
 
 The @code{positions} property allows the vertical position and hence
 the slope of tuplets, slurs, phrasing slurs and beams to be controlled
 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
 @cindex positions property, example
 
 @noindent
 One possibility would be to move the two ends of the phrasing slur
 higher.  We can try setting the left end to 2.5 staff-spaces above the
 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
 a little?  If you try it you'll find it can't be done in this way.
 That's because there are no candidate slurs lower than the one
 already selected, and in this case the @code{positions} property has
 no effect.  However, ties, slurs and phrasing slurs @emph{can} be
 positioned and shaped very precisely when necessary.  To learn how to
 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
 
 @noindent
 This can be resolved by manually moving both ends of the beam
 up from their position at 1.81 staff-spaces below the center line to,
 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}
+@unnumberedsubsubsec The @code{force-hshift} property
 
 We can now see how to apply the final corrections to the Chopin
 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 }
     \\
     \\
     { aes'2 f4 fes }
   >> |
   <c ees aes c>1 |
 }
 @end lilypond
 
 @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.
-
-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
+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
 @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:
 
 @cindex NoteColumn, example of overriding
 @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 |
 }
 @end lilypond
 
 
 @node Real music example
 @subsection Real music example
 
 We end this section on Tweaks by showing the steps to be taken to
 deal with a tricky example which needs several tweaks to produce
 the desired output.  The example has been deliberately chosen to
 illustrate the use of the Notation Reference to resolve unusual
 problems with notation.  It is not representative of the more usual
 engraving process, so please do not let these difficulties put
 you off!  Fortunately, difficulties like these are not very common!
 
 The example is from Chopin's Première Ballade, Op. 23, bars 6 to
 9, the transition from the opening Lento to Moderato.
 Here, first, is what we want the output to look like, but to avoid
 over-complicating the example too much we have left out the
 dynamics, fingering and pedalling.
 
 @c The following should appear as music without code
 @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 {
         \voiceTwo
         c,8~
         % Reposition the c2 to the right of the merged note
         \once \override NoteColumn.force-hshift = #1.0
         % Move the c2 out of the main note column
         % so the merge will work
         \shiftOnn
         c2
       }
       \new Voice {
         \voiceThree
         s8
         % Stem on the d2 must be down to permit merging
         \stemDown
         % Stem on the d2 should be invisible
         \tweak Stem.transparent ##t
-        \tweak Flag.transparent ##t
         d2
       }
       \new Voice {
         \voiceFour
         s4 fis4.
       }
     >> |
     \mergeDifferentlyHeadedOff
     \mergeDifferentlyDottedOff
     g2.\)
   }
 }
 
-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
 }
 
 \score {
   \new PianoStaff <<
     \new Staff = "RH"  <<
       \key g \minor
       \rhMusic
@@ skipping 19 matching lines @@
 voices for the polyphonic passage, as LilyPond is better able to
 avoid collisions if all voices are instantiated explicitly in this
 way.
 
 So let us begin by entering the notes as two variables, setting up
 the staff structure in a score block, and seeing what LilyPond
 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
     % Start polyphonic section of four voices
     <<
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
         s8 d2
       }
       \new Voice {
         \voiceFour
         s4 fis4.
       }
     >> |
     g2.  % continuation of main voice
   }
 }
 
-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
 }
 
 \score {
   \new PianoStaff <<
     \new Staff = "RH"  <<
       \key g \minor
       \rhMusic
     >>
     \new Staff = "LH" <<
       \key g \minor
       \clef "bass"
       \lhMusic
     >>
   >>
 }
 @end lilypond
 
 All the notes are right, but the appearance is far from
 satisfactory.  The tie collides with the change in time signature,
 some notes are not merged together, and several notation elements
 are missing.  Let's first deal with the easier things.  We can
 easily add the left hand slur and the right hand phrasing slur,
 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
     % Start polyphonic section of four voices
     <<
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
         s8 d2
       }
       \new Voice {
         \voiceFour
         s4 fis4.
       }
     >> |
     g2.\)  % continuation of main voice
   }
 }
 
-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
 }
 
 \score {
   \new PianoStaff <<
     \new Staff = "RH"  <<
       \key g \minor
       \rhMusic
@@ skipping 22 matching lines @@
 spaces relative to the center line of the staff.  So the following
 override placed just before the first tied note would move the tie up
 to 3.5 half staff spaces above the center line:
 
 @code{\once \override Tie.staff-position = #3.5}
 
 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 "||"
     \time 6/4
     bes2. r8
     % Start polyphonic section of four voices
     <<
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
         s8 d2
       }
       \new Voice {
         \voiceFour
         s4 fis4.
       }
     >> |
     g2.\)  % continuation of main voice
   }
 }
 
-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
 }
 
 \score {
   \new PianoStaff <<
     \new Staff = "RH"  <<
       \key g \minor
       \rhMusic
     >>
     \new Staff = "LH" <<
       \key g \minor
       \clef "bass"
       \lhMusic
     >>
   >>
 }
 @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
 differently headed and differently dotted notes in
 @ruser{Collision resolution}.  In our example we need to merge both
 types of note for the duration of the polyphonic section in bar 3,
 so using the information we find in the Notation Reference we add
 
 @example
 \mergeDifferentlyHeadedOn
 \mergeDifferentlyDottedOn
 @end example
 
 @noindent
 to the start of that section and
 
 @example
 \mergeDifferentlyHeadedOff
 \mergeDifferentlyDottedOff
 @end example
 
 @noindent
 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
     <<
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
-        c,8~ c2
+        c,8~ 2
       }
       \new Voice {
         \voiceThree
         s8 d2
       }
       \new Voice {
         \voiceFour
         s4 fis4.
       }
     >> |
     \mergeDifferentlyHeadedOff
     \mergeDifferentlyDottedOff
     g2.\)  % continuation of main voice
   }
 }
 
-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
 }
 
 \score {
   \new PianoStaff <<
     \new Staff = "RH"  <<
       \key g \minor
       \rhMusic
@@ skipping 20 matching lines @@
 voices one and three, which have shift off and shift on,
 respectively.  So we have to shift the C a further level still
 using @code{\shiftOnn} to avoid it interfering with the two D's.
 Applying these changes gives:
 
 @cindex Tie, example of overriding
 @cindex staff-position property, example
 
 @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
     <<
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
         % Move the c2 out of the main note column
         % so the merge will work
         c,8~ \shiftOnn c2
       }
       \new Voice {
         \voiceThree
         % Stem on the d2 must be down to permit merging
         s8 \stemDown d2
       }
       \new Voice {
         \voiceFour
         s4 fis4.
       }
     >> |
     \mergeDifferentlyHeadedOff
     \mergeDifferentlyDottedOff
     g2.\)  % continuation of main voice
   }
 }
 
-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
 }
 
 \score {
   \new PianoStaff <<
     \new Staff = "RH"  <<
       \key g \minor
       \rhMusic
@@ skipping 13 matching lines @@
 earlier tweaks: we make the stem transparent, and move the C with
 the @code{force-hshift} property.  Here's the final result:
 
 @cindex NoteColumn, example of overriding
 @cindex force-hshift property, example
 @cindex Stem, example of overriding
 @cindex transparent property, example
 
 @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
     <<
       { c,8 d fis bes a }  % continuation of main voice
       \new Voice {
         \voiceTwo
         c,8~
         % Reposition the c2 to the right of the merged note
         \once \override NoteColumn.force-hshift = #1.0
         % Move the c2 out of the main note column
         % so the merge will work
         \shiftOnn
         c2
       }
       \new Voice {
         \voiceThree
         s8
         % Stem on the d2 must be down to permit merging
         \stemDown
         % Stem on the d2 should be invisible
         \tweak Stem.transparent ##t
-        \tweak Flag.transparent ##t
         d2
       }
       \new Voice {
         \voiceFour
         s4 fis4.
       }
     >> |
     \mergeDifferentlyHeadedOff
     \mergeDifferentlyDottedOff
     g2.\)  % continuation of main voice
   }
 }
 
-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
 }
 
 \score {
   \new PianoStaff <<
     \new Staff = "RH"  <<
       \key g \minor
       \rhMusic
     >>
     \new Staff = "LH" <<
       \key g \minor
       \clef "bass"
       \lhMusic
     >>
   >>
 }
 @end lilypond
 
 
 @node Further tweaking
 @section Further tweaking
 
 @menu
 * Other uses for tweaks::
-* Using variables for tweaks::
+* Using variables for layout adjustments::
 * Style sheets::
 * Other sources of information::
 * Advanced tweaks with Scheme::
 @end menu
 
 @node Other uses for tweaks
 @subsection Other uses for tweaks
 
 @menu
 * Tying notes across voices::
 * 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
-
-@lilypond[quote,fragment,relative=2]
-<< { b8~ b\noBeam } \\ { b8[ g] } >>
+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]
+<< { 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
-
-@lilypond[quote,fragment,relative=2,verbatim]
+and removing the first up-stem and its flag in that voice, the tie
+appears to cross voices:
+
+@funindex \omit
+@cindex Stem, example of removing
+@cindex Flag, example of removing
+@cindex @code{\omit}, example
+@cindex example of @code{\omit}
+
+@lilypond[quote,verbatim]
 <<
   {
-    \tweak Stem.transparent ##t
-    \tweak Flag.transparent ##t
-    b8~ b\noBeam
+    \once \omit Stem
+    \once \omit Flag
+    b'8~ 8\noBeam
   }
 \\
-  { b8[ g] }
+  { b'8[ 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},
-
-@lilypond[quote,fragment,relative=2,verbatim]
-<<
-  {
-    \tweak Stem.transparent ##t
-    \tweak Flag.transparent ##t
-    \tweak Stem.length #8
-    b8~ b\noBeam
-  }
-\\
-  { b8[ 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
-
-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.
+@seealso
+Learning Manual:
+@ref{The once prefix,,The @code{@bs{}once} prefix},
+@ref{The stencil property}.
+
 
 @node Simulating a fermata in MIDI
 @unnumberedsubsubsec Simulating a fermata in MIDI
 
 @cindex stencil property, use of
 @cindex fermata, implementing in MIDI
 
 For outside-staff objects it is usually better to override the
 object's @code{stencil} property rather than its @code{transparent}
 property when you wish to remove it from the printed output.
 Setting the @code{stencil} property of an object to @code{#f} will
 remove that object entirely from the printed output.  This means it
 has no effect on the placement of other objects placed relative to
 it.
 
 For example, if we wished to change the metronome setting in order
 to simulate a fermata in the MIDI output we would not want the
 metronome markings to appear in the printed output, and we would
 not want it to influence the spacing between the two systems or
 the positions of adjacent annotations on the staff.  So setting
 its @code{stencil} property to @code{#f} would be the best way.
 We show here the effect of the two methods:
 
 @cindex MetronomeMark, example of overriding
 @cindex transparent property, example
 
 @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
     a4\fermata |
     % New tempo for next section
     \tempo 4=100
     a4 a a a |
   }
   \layout { }
   \midi { }
 }
 @end lilypond
 
 @cindex MetronomeMark, example of overriding
 @cindex stencil property, example
 
 @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
     a4\fermata |
     % New tempo for next section
     \tempo 4=100
     a4 a a a |
   }
   \layout { }
   \midi { }
 }
 @end lilypond
 
 @noindent
 Both methods remove the metronome mark which lengthens the fermata
 from the printed output, and both affect the MIDI timing as
 required, but the transparent metronome mark in the first line
 forces the following tempo indication too high while the
 second (with the stencil removed) does not.
 
 @seealso
 Music Glossary:
 @rglos{system}.
 
-@node Using variables for tweaks
-@subsection Using variables for tweaks
-
-@cindex variables, using for tweaks
-@cindex using variables for tweaks
-@cindex tweaks, using variables for
+@node Using variables for layout adjustments
+@subsection Using variables for layout adjustments
+
+@cindex variables, using for overrides
+@cindex overrides, using variables for
+@cindex adjustments, using variables for
+@cindex layout adjustments, using variables for
 
 Override commands are often long and tedious to type, and they
 have to be absolutely correct.  If the same overrides are to be
 used many times it may be worth defining variables to hold them.
 
 Suppose we wish to emphasize certain words in lyrics by printing
 them in bold italics.  The @code{\italic} and @code{\bold}
 commands only work within lyrics if they are embedded, together with
 the word or words to be modified, within a @code{\markup} block,
 which makes them tedious to enter.  The need to embed the words
@@ skipping 27 matching lines @@
   \override Lyrics.LyricText.font-series = #'bold
 }
 
 normal = {
   \revert Lyrics.LyricText.font-shape
   \revert Lyrics.LyricText.font-series
 }
 
 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,
 }
 
 VerseTwo = \lyricmode {
   O | \once \emphasize Christ, whose voice the | wa -- ters heard,
 }
 
 VerseThree = \lyricmode {
@@ skipping 33 matching lines @@
 input files that you want to apply your tweaks to?  Or what if you
 simply want to separate your tweaks from the actual music?  This
 is quite easy to do.
 
 Let's look at an example.  Don't worry if you don't understand
 the parts with all the @code{#()}.  This is explained in
 @ref{Advanced tweaks with Scheme}.
 
 @lilypond[quote,verbatim,ragged-right]
 mpdolce =
-#(make-dynamic-script
-  #{ \markup { \hspace #0
-               \translate #'(5 . 0)
-               \line { \dynamic "mp"
-                       \text \italic "dolce" } }
-  #})
+  \tweak self-alignment-X #-0.6
+  #(make-dynamic-script
+    #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})
 
 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 |
   g8(\! fis)-. e( d)-. cis2 |
 }
 @end lilypond
 
 Let's do something about the @code{mpdolce} and @code{inst} definitions.
 They produce the output we desire, but we might want to use them in
 another piece.  We could simply copy-and-paste them at the top of every
 file, but that's an annoyance.  It also leaves those definitions in our
 input files, and I personally find all the @code{#()} somewhat ugly.
 Let's hide them in another file:
 
 @example
 %%% save this to a file called "definitions.ily"
 mpdolce =
-#(make-dynamic-script
-  #@{ \markup @{ \hspace #0
-               \translate #'(5 . 0)
-               \line @{ \dynamic "mp"
-                       \text \italic "dolce" @} @}
-  #@})
+  \tweak self-alignment-X #-0.6
+  #(make-dynamic-script
+    #@{ \markup @{ \dynamic mp \normal-text \italic \bold dolce @} #@})
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #@{ <>^\markup \bold \box #string #@})
 @end example
 
 We will refer to this file using the @code{\include} command near
 the top of the music file.  (The extension @file{.ily} is used to
 distinguish this included file, which is not meant to be compiled
 on its own, from the main file.)
 Now let's modify our music (let's save this file as @file{music.ly}).
 
 @c  We have to do this awkward example/lilypond-non-verbatim
 @c  because we can't do the \include stuff in the manual.
 
 @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 |
   g8(\! fis)-. e( d)-. cis2 |
 @}
 @end example
 
 @lilypond[quote,ragged-right]
 mpdolce =
-#(make-dynamic-script
-  #{ \markup { \hspace #0
-               \translate #'(5 . 0)
-               \line { \dynamic "mp"
-                       \text \italic "dolce" } }
-  #})
+  \tweak self-alignment-X #-0.6
+  #(make-dynamic-script
+    #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})
 
 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 |
   g8(\! fis)-. e( d)-. cis2 |
 }
 @end lilypond
 
 That looks better, but let's make a few changes.  The glissando is hard
 to see, so let's make it thicker and closer to the note heads.  Let's
 put the metronome marking above the clef, instead of over the first
 note.  And finally, my composition professor hates @q{C} time signatures,
 so we'd better make that @q{4/4} instead.
 
 Don't change @file{music.ly}, though.  Replace our @file{definitions.ily}
 with this:
 
 @example
 %%%  definitions.ily
 mpdolce =
-#(make-dynamic-script
-  #@{ \markup @{ \hspace #0
-               \translate #'(5 . 0)
-               \line @{ \dynamic "mp"
-                       \text \italic "dolce" @} @}
-  #@})
+  \tweak self-alignment-X #-0.6
+  #(make-dynamic-script
+    #@{ \markup @{ \dynamic mp \normal-text \italic \bold dolce @} #@})
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #@{ <>^\markup \bold \box #string #@})
 
 \layout@{
   \context @{
     \Score
-    \override MetronomeMark.extra-offset = #'(-9 . 0)
+    \override MetronomeMark.extra-offset = #'(-5 . 0)
     \override MetronomeMark.padding = #'3
   @}
   \context @{
     \Staff
     \override TimeSignature.style = #'numbered
   @}
   \context @{
     \Voice
     \override Glissando.thickness = #3
     \override Glissando.gap = #0.1
   @}
 @}
 @end example
 
 @lilypond[quote,ragged-right]
 mpdolce =
-#(make-dynamic-script
-  #{ \markup { \hspace #0
-               \translate #'(5 . 0)
-               \line { \dynamic "mp"
-                       \text \italic "dolce" } }
-  #})
+  \tweak self-alignment-X #-0.6
+  #(make-dynamic-script
+    #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #{ <>^\markup \bold \box #string #})
 
 \layout{
   \context {
     \Score
-    \override MetronomeMark.extra-offset = #'(-9 . 0)
+    \override MetronomeMark.extra-offset = #'(-5 . 0)
     \override MetronomeMark.padding = #'3
   }
   \context {
     \Staff
     \override TimeSignature.style = #'numbered
   }
   \context {
     \Voice
     \override Glissando.thickness = #3
     \override Glissando.gap = #0.1
   }
 }
 
-\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 |
   g8(\! fis)-. e( d)-. cis2 |
 }
 @end lilypond
 
 That looks nicer!  But now suppose that I want to publish this
 piece.  My composition professor doesn't like @q{C} time
 signatures, but I'm somewhat fond of them.  Let's copy the
 current @file{definitions.ily} to @file{web-publish.ily} and
 modify that.  Since this music is aimed at producing a pdf which
 will be displayed on the screen, we'll also increase the
 overall size of the output.
 
 @example
 %%%  web-publish.ily
 mpdolce =
-#(make-dynamic-script
-  #@{ \markup @{ \hspace #0
-               \translate #'(5 . 0)
-               \line @{ \dynamic "mp"
-                       \text \italic "dolce" @} @}
-  #@})
+  \tweak self-alignment-X #-0.6
+  #(make-dynamic-script
+    #@{ \markup @{ \dynamic mp \normal-text \italic \bold dolce @} #@})
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #@{ <>^\markup \bold \box #string #@})
 
 #(set-global-staff-size 23)
 
 \layout@{
   \context @{
     \Score
-    \override MetronomeMark.extra-offset = #'(-9 . 0)
+    \override MetronomeMark.extra-offset = #'(-5 . 0)
     \override MetronomeMark.padding = #'3
   @}
   \context @{
     \Staff
   @}
   \context @{
     \Voice
     \override Glissando.thickness = #3
     \override Glissando.gap = #0.1
   @}
 @}
 @end example
 
 @lilypond[quote,ragged-right]
 mpdolce =
-#(make-dynamic-script
-  #{ \markup { \hspace #0
-               \translate #'(5 . 0)
-               \line { \dynamic "mp"
-                       \text \italic "dolce" } }
-  #})
+  \tweak self-alignment-X #-0.6
+  #(make-dynamic-script
+    #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})
 
 inst =
 #(define-music-function
-     (parser location string)
+     (string)
      (string?)
    #{ <>^\markup \bold \box #string #})
 
 #(set-global-staff-size 23)
 
 \layout{
   \context { \Score
-    \override MetronomeMark.extra-offset = #'(-9 . 0)
+    \override MetronomeMark.extra-offset = #'(-5 . 0)
     \override MetronomeMark.padding = #'3
   }
   \context { \Voice
     \override Glissando.thickness = #3
     \override Glissando.gap = #0.1
   }
 }
 
-\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 |
   g8(\! fis)-. e( d)-. cis2 |
 }
 @end lilypond
 
 Now in our music, I simply replace
 @code{\include "definitions.ily"} with
 @code{\include "web-publish.ily"}.  Of course, we could make this
@@ skipping 87 matching lines @@
 
 @itemize
 @item @file{ly/} - contains files in LilyPond format
 @item @file{scm/} - contains files in Scheme format
 @end itemize
 
 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 = @{
   \override Tie.dash-period = #0.75
   \override Tie.dash-fraction = #0.1
 @}
 @end example
 
 If you do not like the default values these predefined commands can
 be redefined easily, just like any other variable, at the
@@ skipping 83 matching lines @@
        ;;   Return rainbow colors
        ((1) (x11-color 'red    ))  ; for C
        ((2) (x11-color 'orange ))  ; for D
        ((3) (x11-color 'yellow ))  ; for E
        ((4) (x11-color 'green  ))  ; for F
        ((5) (x11-color 'blue   ))  ; for G
        ((6) (x11-color 'purple ))  ; for A
        ((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 |
 }
 @end lilypond
 
 Further examples showing the use of these programmable interfaces
 can be found in @rextend{Callback functions}.