Guide, node Updating translation committishes..
@end ignore
-@c \version "2.19.2"
+@c \version "2.19.16"
@node Tweaking output
@chapter Tweaking output
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
* The once prefix::
* The overrideProperty command::
* The tweak command::
+* The single prefix::
@end menu
@node The override command
predefined commands to limit their effect to one musical moment:
@lilypond[quote,verbatim,relative=1]
-c4 d
-\once \stemDown
-e4 f |
-g4 a
+c4( d)
+\once \slurDashed
+e4( f) |
+g4( a)
\once \hideNotes
-b c |
+b( c) |
@end lilypond
However, predefined commands of the form @code{\@dots{}Neutral},
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
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
@cindex center
@cindex neutral
-The following example shows in bar 1 the default behavior of stems,
-with those on high notes pointing down and those on low notes pointing
-up, followed by four notes with all stems forced down, four notes with
-all stems forced up, and finally four notes reverted back to the
-default behavior.
+The following example shows the default positioning of slurs in the
+first bar, with slurs starting on high notes positioned above the notes
+and those starting on low notes positioned below, followed by a bar
+with both slurs forced down, a bar with both slurs forced up, and
+finally a bar with both slurs reverted back to the default behavior.
-@cindex Stem, example of overriding
+@cindex Slur, example of overriding
@cindex direction property, example
-@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
-a4 g c a |
-\override Stem.direction = #DOWN
-a4 g c a |
-\override Stem.direction = #UP
-a4 g c a |
-\revert Stem.direction
-a4 g c a |
+@lilypond[quote,verbatim,relative=2]
+a4( g) c( a) |
+\override Slur.direction = #DOWN
+a4( g) c( a) |
+\override Slur.direction = #UP
+a4( g) c( a) |
+\revert Slur.direction
+a4( g) c( a) |
@end lilypond
-Here we use the constants @code{DOWN} and @code{UP}.
+Here we have used the constants @code{DOWN} and @code{UP}.
These have the values @w{@code{-1}} and @code{+1} respectively, and
these numerical values may be used instead. The value @code{0}
may also be used in some cases. It is simply treated as meaning
-@code{UP} for stems, but for some objects it means @q{center}.
+@code{UP} for slurs, but for some objects it means @q{center}.
There is a constant, @code{CENTER} which has the value @code{0}.
However, these explicit overrides are not usually used, as there are
@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,verbatim,relative=2]
+a4( g) c( a) |
+a4^( g) c_( a) |
+@end lilypond
+
@node Fingering
@unnumberedsubsubsec Fingering
@cindex Fingering, example of overriding
@cindex extra-offset property, example
-@lilypond[quote,fragment,relative=1,verbatim]
-\stemUp
+@lilypond[quote,relative=1,verbatim]
f4-5
\once \override Fingering.extra-offset = #'(-0.3 . -1.8)
f4-5
Here's a further example. We see that the beams
collide with the ties:
-@lilypond[quote,verbatim,fragment,ragged-right]
+@lilypond[quote,verbatim,fragment,ragged-right,relative=1]
{
\time 4/2
<<
- { c'1 ~ 2. e'8 f' }
+ { c1~ 2. e8 f }
\\
- { 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 ~ 2. e'8 f' }
+ { c,,1~ 2. e8 f }
\\
- { e''8 e'' e'' e'' e'' e'' e'' e'' f''2 g'' }
+ {
+ e'8 e e e
+ e e e e
+ f2 g
+ }
>>
}
@end lilypond
@cindex Beam, example of overriding
@cindex positions property, example
-@lilypond[quote,verbatim,fragment,ragged-right]
+@lilypond[quote,verbatim,ragged-right,relative=1]
{
\time 4/2
<<
- { c'1 ~ 2. e'8 f' }
+ { c1~ 2. e8 f }
\\
{
\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 ~ 2. e'8 f' }
+ { c,,1~ 2. e8 f }
\\
- { e''8 e'' e'' e'' e'' e'' e'' e'' f''2 g'' }
+ {
+ 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
@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. We might expect to correct this by using @code{\shiftOff}, but
-this will cause warnings about clashing note columns. Instead, we
-set @code{force-hshift}, which is a property of @code{NoteColumn},
-of this note to zero.
+note, so we use @code{\shiftOff}.
In the second chord we prefer the F to line up with the A-flat and
the lowest note to be positioned slightly right to avoid a collision
{ <ees, c>2 \once \override NoteColumn.force-hshift = 0.5 des }
\\
\\
- { \once \override NoteColumn.force-hshift = 0 aes'2
- \once \override NoteColumn.force-hshift = 0 f4 fes }
+ { \once \shiftOff aes'2 \once \shiftOff f4 fes }
>> |
<c ees aes c>1 |
}
\time 6/4
\mergeDifferentlyHeadedOn
\mergeDifferentlyDottedOn
- bes2.^\markup { \bold "Moderato" } r8
+ bes2.\tempo "Moderato" r8
<<
{ c,8 d fis bes a }
\new Voice {
@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
bes1~ |
\bar "||"
\time 6/4
- bes2.^\markup { \bold "Moderato" } r8
+ bes2.\tempo "Moderato" r8
\mergeDifferentlyHeadedOn
\mergeDifferentlyDottedOn
% Start polyphonic section of four voices
bes1~ |
\bar "||"
\time 6/4
- bes2.^\markup { \bold "Moderato" } r8
+ bes2.\tempo "Moderato" r8
\mergeDifferentlyHeadedOn
\mergeDifferentlyDottedOn
% Start polyphonic section of four voices
bes1~ |
\bar "||"
\time 6/4
- bes2.^\markup { \bold "Moderato" } r8
+ bes2.\tempo "Moderato" r8
\mergeDifferentlyHeadedOn
\mergeDifferentlyDottedOn
% Start polyphonic section of four 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
+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
}
\\
>>
@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
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 = @{