From 63e280b6c609d307b1cb9aa1852fce7862c39738 Mon Sep 17 00:00:00 2001 From: Trevor Daniels Date: Tue, 14 Oct 2014 09:10:06 +0100 Subject: [PATCH] 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. --- Documentation/learning/tweaks.itely | 130 +++++++++++++++------------- 1 file changed, 72 insertions(+), 58 deletions(-) diff --git a/Documentation/learning/tweaks.itely b/Documentation/learning/tweaks.itely index 160c0e3901..b759708708 100644 --- 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'' { + 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 -- 2.39.2