From ce1c0fabb3d5ac18e61fb8fcc91a3990714553c2 Mon Sep 17 00:00:00 2001 From: David Kastrup Date: Fri, 18 May 2012 18:04:41 +0200 Subject: [PATCH] Issue 2539: Redocument tweak This adjusts the documentation of \tweak to take into account a) EventChord not intervening uncalled for (issue 2240) b) the ability to specify indirect grobs (issue 2540) --- Documentation/changes.tely | 29 ++++++--- Documentation/learning/tweaks.itely | 63 +++++++++++------- .../notation/changing-defaults.itely | 64 ++++++++++--------- 3 files changed, 93 insertions(+), 63 deletions(-) diff --git a/Documentation/changes.tely b/Documentation/changes.tely index e69766cacc..632ce2042f 100644 --- a/Documentation/changes.tely +++ b/Documentation/changes.tely @@ -140,6 +140,17 @@ code operative. The following three items are consequences of this change. +@item +The repetitive chord entry aid @code{q} has been reimplemented. +Repeated chords are now replaced right before interpreting a music +expression. In case the user wants to retain some events of the +original chord, he can run the repeat chord replacement function +@code{\chordRepeats} manually. + +@item +String numbers and right hand fingerings on single notes now appear +without having to be written inside of chord brackets. + @item Music functions now work the same when used inside or outside of chords, including all the possibilities of argument parsing. Music variables @@ -155,15 +166,15 @@ notes without needing to wrap them in a chord. Using it on command events and lyrics is now possible, but not likely to give results yet. @item -The repetitive chord entry aid @code{q} has been reimplemented. -Repeated chords are now replaced right before interpreting a music -expression. In case the user wants to retain some events of the -original chord, he can run the repeat chord replacement function -@code{\chordRepeats} manually. - -@item -String numbers and right hand fingerings on single notes now appear -without having to be written inside of chord brackets. +@code{\tweak} now takes an optional layout object specification. It can +be used for tweaking layout objects that are only indirectly caused by +the tweaked event, like accidentals, stems, and flags: + +@lilypond[verbatim,quote,ragged-right,relative=2] +<\tweak Accidental #'color #red cis4 + \tweak Accidental #'color #green es + g> +@end lilypond @item Scheme expressions inside of embedded Lilypond (@code{#@{@dots{}#@}}) diff --git a/Documentation/learning/tweaks.itely b/Documentation/learning/tweaks.itely index 1af29f9eb4..675e585ca5 100644 --- a/Documentation/learning/tweaks.itely +++ b/Documentation/learning/tweaks.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.15.10" +@c \version "2.15.39" @node Tweaking output @chapter Tweaking output @@ -348,12 +348,10 @@ 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. However, -it is effective only on objects which are created directly from -the input stream, essentially note heads and articulations; -objects such as stems and accidentals are created later and -cannot be tweaked in this way. +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: @@ -366,13 +364,12 @@ a chord would be changed in this way: 4 @end lilypond -Note that the syntax of @code{\tweak} is different from that -of the @code{\override} command. Neither the context nor the -layout object should be specified; in fact, it would generate -an error to do so. These are both implied by the following -item in the input stream. Note also that an equals sign should -not be present. So the general syntax of the -@code{\tweak} command is simply +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} @@ -396,6 +393,26 @@ 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> +@end lilypond + +This long form of the @code{\tweak} command can be described as +@example +\tweak @var{layout-object} #'@var{layout-property} @var{value} +@end example + @cindex tuplets, nested @cindex triplets, nested @cindex bracket, tuplet @@ -2956,8 +2973,8 @@ rhMusic = \relative c'' { % Stem on the d2 must be down to permit merging \stemDown % Stem on the d2 should be invisible - \once \override Stem #'transparent = ##t - \once \override Flag #'transparent = ##t + \tweak Stem #'transparent ##t + \tweak Flag #'transparent ##t d2 } \new Voice { @@ -3391,8 +3408,8 @@ rhMusic = \relative c'' { % Stem on the d2 must be down to permit merging \stemDown % Stem on the d2 should be invisible - \once \override Stem #'transparent = ##t - \once \override Flag #'transparent = ##t + \tweak Stem #'transparent ##t + \tweak Flag #'transparent ##t d2 } \new Voice { @@ -3474,8 +3491,8 @@ cross voices: @lilypond[quote,fragment,relative=2,verbatim] << { - \once \override Stem #'transparent = ##t - \once \override Flag #'transparent = ##t + \tweak Stem #'transparent ##t + \tweak Flag #'transparent ##t b8~ b\noBeam } \\ @@ -3490,9 +3507,9 @@ too much, we can lengthen the stem by setting the @lilypond[quote,fragment,relative=2,verbatim] << { - \once \override Stem #'transparent = ##t - \once \override Flag #'transparent = ##t - \once \override Stem #'length = #8 + \tweak Stem #'transparent ##t + \tweak Flag #'transparent ##t + \tweak Stem #'length #8 b8~ b\noBeam } \\ diff --git a/Documentation/notation/changing-defaults.itely b/Documentation/notation/changing-defaults.itely index d533d1a48f..8d1f37effa 100644 --- a/Documentation/notation/changing-defaults.itely +++ b/Documentation/notation/changing-defaults.itely @@ -8,7 +8,7 @@ Guide, node Updating translation committishes.. @end ignore -@c \version "2.15.20" +@c \version "2.15.39" @node Changing defaults @chapter Changing defaults @@ -1801,11 +1801,12 @@ accomplished with the @code{\tweak} command, which has the following syntax: @example -\tweak #'@code{grob-property} #@code{value} +\tweak @var{layout-object} #'@var{grob-property} @var{value} @end example -The @code{\tweak} command applies to the object that immediately -follows @code{value} in the music stream. +Specifying @var{layout-object} is optional. +The @code{\tweak} command applies to the music object that immediately +follows @var{value} in the music stream. @ignore In some cases, it is possible to take a short-cut for tuning @@ -1905,23 +1906,33 @@ c-\tweak #'thickness #5 ( d e f) For the @code{\tweak} command to work, it must remain immediately adjacent to the object to which it is to apply after the input file has been converted to a music stream. -At times, LilyPond may insert additional items into the music stream -during the parsing process. For example, when a note that is not -explicitly part of a chord will be placed in a chord by LilyPond, -so notes to be modified with @code{\tweak} must be placed inside -a chord construct: +Tweaking a whole chord does not do anything since its music event +only acts as a container, and all layout objects are created from events +inside of the @code{EventChord}: @lilypond[relative=2,verbatim,quote] \tweak #'color #red c4 -<\tweak #'color #red c>4 +\tweak #'color #red 4 +<\tweak #'color #red c e>4 @end lilypond -The @code{\tweak} command cannot be used to modify any item -that does not appear explicitly in the input file. In particular -it cannot be used to modify stems, -beams or accidentals directly, since these are generated later by -note heads, rather than by music elements in the input stream. -Nor can @code{\tweak} be used to modify clefs or time +The simple @code{\tweak} command cannot be used to modify any object +that is not directly created from the input. In particular +it will not affect stems, automatic +beams or accidentals, since these are generated later by +\@code{NoteHead} layout objects rather than by music elements in the +input stream. + +Such indirectly created layout objects can be tweaked using the explicit +form of the @code{\tweak} command: + +@lilypond[relative=2,verbatim,quote] +\tweak Stem #'color #red +\tweak Beam #'color #green c8 e +4 +@end lilypond + +@code{\tweak} cannot be used to modify clefs or time signatures, since these become separated from any preceding @code{\tweak} command in the input stream by the automatic insertion of extra elements required to specify the context. @@ -1954,12 +1965,6 @@ Extending LilyPond: @rextend{Displaying music expressions}. @knownissues -@cindex tweaks in a variable - -The @code{\tweak} command cannot be used inside a variable. - -@cindex tweaks in lyrics -The @code{\tweak} commands cannot be used in @code{\lyricmode}. @cindex tweaking control points @cindex control points, tweaking @@ -3914,19 +3919,16 @@ padText = In addition to numbers, we can use music expressions such as notes for arguments to music functions: -@c TODO: use a better example (the music argument is redundant). - @lilypond[quote,verbatim,ragged-right] custosNote = #(define-music-function (parser location note) (ly:music?) #{ - \once \override Voice.NoteHead #'stencil = - #ly:text-interface::print - \once \override Voice.NoteHead #'text = - \markup \musicglyph #"custodes.mensural.u0" - \once \override Voice.Stem #'stencil = ##f + \tweak NoteHead #'stencil #ly:text-interface::print + \tweak NoteHead #'text + \markup \musicglyph #"custodes.mensural.u0" + \tweak Stem #'stencil ##f $note #}) @@ -3939,7 +3941,7 @@ Substitution functions with multiple arguments can be defined: tempoPadded = #(define-music-function (parser location padding tempotext) - (number? string?) + (number? markup?) #{ \once \override Score.MetronomeMark #'padding = #padding \tempo \markup { \bold #tempotext } @@ -3948,7 +3950,7 @@ tempoPadded = \relative c'' { \tempo \markup { "Low tempo" } c4 d e f g1 - \tempoPadded #4.0 #"High tempo" + \tempoPadded #4.0 "High tempo" g4 f e d c1 } @end lilypond -- 2.39.2