Guide, node Updating translation committishes..
@end ignore
-@c \version "2.17.20"
+@c \version "2.19.2"
@node Tweaking output
@chapter Tweaking output
@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::
@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
@end lilypond
-@node The \revert command
-@unnumberedsubsubsec The @code{\revert} command
+@node The revert command
+@unnumberedsubsubsec The @code{@bs{}revert} command
@cindex revert command
@end lilypond
-@node The \once prefix
-@unnumberedsubsubsec The @code{\once} prefix
+@node The once prefix
+@unnumberedsubsubsec The @code{@bs{}once} prefix
@funindex \once
@funindex once
effect.
-@node The \overrideProperty command
-@unnumberedsubsubsec The @code{\overrideProperty} command
+@node The overrideProperty command
+@unnumberedsubsubsec The @code{@bs{}overrideProperty} command
@cindex overrideProperty command
@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
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]
@menu
* The outside-staff-priority property::
-* The \textLengthOn command::
+* The textLengthOn command::
* Dynamics placement::
* Grob sizing::
@end menu
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
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 paper variables} and
@ruser{Flexible vertical spacing within systems} for more
details.
@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.
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
@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
@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 a\mp b\p
+\override DynamicLineSpanner.staff-padding = #3
+a4\f b\mf a\p b\mp
@end lilypond
{
\time 4/2
<<
- { c'1 ~ c'2. e'8 f' }
+ { c'1 ~ 2. e'8 f' }
\\
{ e''8 e'' e'' e'' e'' e'' e'' e'' f''2 g'' }
>>
<<
- { c'1 ~ c'2. e'8 f' }
+ { c'1 ~ 2. e'8 f' }
\\
{ e''8 e'' e'' e'' e'' e'' e'' e'' f''2 g'' }
>>
{
\time 4/2
<<
- { c'1 ~ c'2. e'8 f' }
+ { c'1 ~ 2. e'8 f' }
\\
{
\override Beam.positions = #'(-1 . -1)
}
>>
<<
- { c'1 ~ c'2. e'8 f' }
+ { c'1 ~ 2. e'8 f' }
\\
{ e''8 e'' e'' e'' e'' e'' e'' e'' f''2 g'' }
>>
@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. 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.
+
+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:
<<
{ c2 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 \override NoteColumn.force-hshift = 0 aes'2
+ \once \override NoteColumn.force-hshift = 0 f4 fes }
>> |
<c ees aes c>1 |
}
{ c,8 d fis bes a } % continuation of main voice
\new Voice {
\voiceTwo
- c,8~ c2
+ c,8~ 2
}
\new Voice {
\voiceThree
{ c,8 d fis bes a } % continuation of main voice
\new Voice {
\voiceTwo
- c,8~ c2
+ c,8~ 2
}
\new Voice {
\voiceThree
{ c,8 d fis bes a } % continuation of main voice
\new Voice {
\voiceTwo
- c,8~ c2
+ c,8~ 2
}
\new Voice {
\voiceThree
{ c,8 d fis bes a } % continuation of main voice
\new Voice {
\voiceTwo
- c,8~ c2
+ c,8~ 2
}
\new Voice {
\voiceThree
with the tied notes in one of them
@lilypond[quote,fragment,relative=2]
-<< { b8~ b\noBeam } \\ { b8[ g] } >>
+<< { b8~ 8\noBeam } \\ { b8[ g] } >>
@end lilypond
@noindent
<<
{
\tweak Stem.transparent ##t
- b8~ b\noBeam
+ b8~ 8\noBeam
}
\\
{ b8[ g] }
{
\tweak Stem.transparent ##t
\tweak Stem.length #8
- b8~ b\noBeam
+ b8~ 8\noBeam
}
\\
{ b8[ g] }
\single \hide Stem
\single \hide Flag
\tweak Stem.length #8
- b8~ b\noBeam
+ b8~ 8\noBeam
}
\\
{ b8[ g] }
@ref{Advanced tweaks with Scheme}.
@lilypond[quote,verbatim,ragged-right]
-mpdolce = -\tweak #'self-alignment-X #-0.6 #
- (make-dynamic-script
- (markup #:dynamic "mp"
- #:normal-text #:italic "dolce" ))
+mpdolce =
+ \tweak self-alignment-X #-0.6
+ #(make-dynamic-script
+ #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})
inst =
#(define-music-function
@example
%%% save this to a file called "definitions.ily"
-mpdolce = -\tweak #'self-alignment-X #-0.6 #
- (make-dynamic-script
- (markup #:dynamic "mp"
- #:normal-text #:italic "dolce" ))
+mpdolce =
+ \tweak self-alignment-X #-0.6
+ #(make-dynamic-script
+ #@{ \markup @{ \dynamic mp \normal-text \italic \bold dolce @} #@})
inst =
#(define-music-function
@end example
@lilypond[quote,ragged-right]
-mpdolce = -\tweak #'self-alignment-X #-0.6 #
- (make-dynamic-script
- (markup #:dynamic "mp"
- #:normal-text #:italic "dolce" ))
+mpdolce =
+ \tweak self-alignment-X #-0.6
+ #(make-dynamic-script
+ #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})
inst =
#(define-music-function
@example
%%% definitions.ily
-mpdolce = -\tweak #'self-alignment-X #-0.6 #
- (make-dynamic-script
- (markup #:dynamic "mp"
- #:normal-text #:italic "dolce" ))
+mpdolce =
+ \tweak self-alignment-X #-0.6
+ #(make-dynamic-script
+ #@{ \markup @{ \dynamic mp \normal-text \italic \bold dolce @} #@})
inst =
#(define-music-function
@end example
@lilypond[quote,ragged-right]
-mpdolce = -\tweak #'self-alignment-X #-0.6 #
- (make-dynamic-script
- (markup #:dynamic "mp"
- #:normal-text #:italic "dolce" ))
+mpdolce =
+ \tweak self-alignment-X #-0.6
+ #(make-dynamic-script
+ #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})
inst =
#(define-music-function
@example
%%% web-publish.ily
-mpdolce = -\tweak #'self-alignment-X #-0.6 #
- (make-dynamic-script
- (markup #:dynamic "mp"
- #:normal-text #:italic "dolce" ))
+mpdolce =
+ \tweak self-alignment-X #-0.6
+ #(make-dynamic-script
+ #@{ \markup @{ \dynamic mp \normal-text \italic \bold dolce @} #@})
inst =
#(define-music-function
@end example
@lilypond[quote,ragged-right]
-mpdolce = -\tweak #'self-alignment-X #-0.6 #
- (make-dynamic-script
- (markup #:dynamic "mp"
- #:normal-text #:italic "dolce" ))
+mpdolce =
+ \tweak self-alignment-X #-0.6
+ #(make-dynamic-script
+ #{ \markup { \dynamic mp \normal-text \italic \bold dolce } #})
inst =
#(define-music-function
projects / lilypond.git / blobdiff