Doc: Issue 4162: tying across voices and \single example

  Correct the example showing how to generate a cross-voice tie

  Separate the explanation of \single, expand it, and show when
  is it useful.

diff --git a/Documentation/learning/tweaks.itely b/Documentation/learning/tweaks.itely
index 160c0e390114e773964043530e9f7d29e1699d87..b7597087080c33bce6e503cd78e735fdf6990bef 100644 (file)
--- a/Documentation/learning/tweaks.itely
+++ b/Documentation/learning/tweaks.itely
@@ -187,6 +187,7 @@ the types of objects and properties from their names.
 * The once prefix::
 * The overrideProperty command::
 * The tweak command::
+* The single prefix::
 @end menu
 
 @node The override command
@@ -521,6 +522,60 @@ appearance may be modified in the usual way with
 Notation Reference:
 @ruser{The tweak command}.
 
+@node The single prefix
+@unnumberedsubsubsec The @code{@bs{}single} prefix
+
+@funindex \single
+@cindex tweak, generated from override
+
+Suppose we wanted to emphasize particular note heads by coloring them
+red and increasing their size, and to make it easy suppose also we
+have defined a function to do this:
+
+@lilypond[quote,verbatim]
+emphNoteHead = {
+  \override NoteHead.color = #red
+  \override NoteHead.font-size = 2
+}
+\relative c'' {
+  c4 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'' {
+   <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
@@ -3803,56 +3858,38 @@ lhMusic = \relative c' {
 * Simulating a fermata in MIDI::
 @end menu
 
-@cindex transparent property, use of
-@cindex objects, making invisible
 @cindex removing objects
 @cindex objects, removing
-@cindex hiding objects
-@cindex objects, hiding
-@cindex invisible objects
-@cindex objects, invisible
 
 @node Tying notes across voices
 @unnumberedsubsubsec Tying notes across voices
 
 @cindex tying notes across voices
 
-The following example demonstrates how to connect notes in
-different voices using ties.  Normally, only two notes in the
-same voice can be connected with ties.  By using two voices,
-with the tied notes in one of them
+The following example demonstrates how to connect notes in different
+voices using ties.  Normally, only notes in the same voice can be
+connected with ties.  By using two voices, with the tied notes in one
+of them
 
 @lilypond[quote,fragment,relative=2]
 << { b8~ 8\noBeam } \\ { b8[ g] } >>
 @end lilypond
 
 @noindent
-and blanking the first up-stem in that voice, the tie appears to
-cross voices:
-
-@cindex Stem, example of overriding
-@cindex transparent property, example
+and removing the first up-stem and its flag in that voice, the tie
+appears to cross voices:
 
-@lilypond[quote,fragment,relative=2,verbatim]
-<<
-  {
-    \tweak Stem.transparent ##t
-    b8~ 8\noBeam
-  }
-\\
-  { b8[ g] }
->>
-@end lilypond
-
-To make sure that the just-blanked stem doesn't squeeze the tie
-too much, we can lengthen the stem by setting the
-@code{length} to @code{8},
+@funindex \omit
+@cindex Stem, example of removing
+@cindex Flag, example of removing
+@cindex @code{\omit}, example
+@cindex example of @code{\omit}
 
 @lilypond[quote,fragment,relative=2,verbatim]
 <<
   {
-    \tweak Stem.transparent ##t
-    \tweak Stem.length #8
+    \once \omit Stem
+    \once \omit Flag
     b8~ 8\noBeam
   }
 \\
@@ -3860,34 +3897,11 @@ too much, we can lengthen the stem by setting the
 >>
 @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~ 8\noBeam
-  }
-\\
-  { b8[ g] }
->>
-@end lilypond
+@seealso
+Learning Manual:
+@ref{The once prefix,,The @code{@bs{}once} prefix},
+@ref{The stencil property}.
 
-In this particular case, the difference to @code{\once \hide} is
-not apparent.  It is important when there are several objects at
-the same point in musical time (like noteheads in a chord).  In
-that case, @code{\once} will affect all of those objects while
-@code{\single} will only affect a single one, the one generated by
-the immediately following music expression.
 
 @node Simulating a fermata in MIDI
 @unnumberedsubsubsec Simulating a fermata in MIDI