version that you are working on. See TRANSLATION for details.
@end ignore
+@c \version "2.11.38"
+
@node Tweaking output
@chapter Tweaking output
@node Objects and interfaces
@subsection Objects and interfaces
-@cindex Objects
-@cindex Grobs
-@cindex Spanners
-@cindex Interfaces
+@cindex objects
+@cindex grobs
+@cindex spanners
+@cindex interfaces
Tweaking involves modifying the internal operation and structures
of the LilyPond program, so we must first introduce some terms
above, and so they too all have properties associated with them,
such as their position, size, color, etc.
-Some layout objects are still more specialised. Phrasing slurs,
-crescendo hairpins, ottavo marks, and many other grobs are not
-localised in a single place -- they have a starting point, an
+Some layout objects are still more specialized. Phrasing slurs,
+crescendo hairpins, ottava marks, and many other grobs are not
+localized in a single place -- they have a starting point, an
ending point, and maybe other properties concerned with their
shape. Objects with an extended shape like these are called
@q{Spanners}.
operations these common actions and properties are grouped
together in an object called a @code{grob-interface}. There
are many other groupings of common properties like this, each
-one given a name ending in @code{-interface}. In total there
+one given a name ending in @code{interface}. In total there
are over 100 such interfaces. We shall see later why this is
of interest and use to the user.
@ref{Contexts and engravers}. Here for reference is a list
of the most common object and property types together with
the conventions for naming them and a couple of examples of
-some real names. We have used A to stand for any capitalised
+some real names. We have used A to stand for any capitalized
alphabetic character and aaa to stand for any number of
lower-case alphabetic characters. Other characters are used
verbatim.
As we shall see shortly, the properties of different types of
object are modified by different commands, so it is useful to
-be able to recognise the type of object from the names of its
+be able to recognize the type of object from the names of its
properties.
@node Tweaking methods
@subsection Tweaking methods
+@strong{\override command}
+
+@cindex override command
+@funindex \override
+
We have already met the commands @code{\set} and @code{\with},
used to change the properties of @strong{contexts} and to remove
and add @strong{engravers}, in
@ref{Modifying context properties} and @ref{Adding
-and removing engravers}. We now must meet one more command.
+and removing engravers}. We now must meet some more important
+commands.
The command to change the properties of @strong{layout objects} is
@code{\override}. Because this command has to modify
The general syntax of this command is:
@example
-\override @emph{context}.@emph{layout_object} #'@emph{layout_property} = #@emph{value}
+\override @emph{context}.@emph{layout_object}
+ #'@emph{layout_property} = #@emph{value}
@end example
@noindent
This will set the property with the name @emph{layout_property}
-of the layout object with the name
+of the layout object with the name
@emph{layout_object}, which is a member of the @emph{context}
context, to the value @emph{value}.
@code{Lyrics}, and we shall omit it in many of the following
examples. We shall see later when it must be specified.
+Later sections deal comprehensively with properties and their
+values, but to illustrate the format and use of these commands
+we shall use just a few simple properties and values which are
+easily understood.
+
For now, don't worry about the @code{#'}, which must precede the
layout property, and the @code{#}, which must precede the value.
These must always be present in exactly this form. This is the
most common command used in tweaking, and most of the rest of
this chapter will be directed to presenting examples of how it is
-used.
+used. Here is a simple example to change the color of the
+note head:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+c d
+\override NoteHead #'color = #red
+e f g
+\override NoteHead #'color = #green
+a b c
+@end lilypond
+
+@strong{\revert command}
+
+@cindex revert command
+@funindex \revert
Once overridden, the property retains its new value until it is
overridden again or a @code{\revert} command is encountered.
Again, just like @emph{context} in the @code{\override} command,
@emph{context} is often not needed. It will be omitted
-in many of the following examples.
+in many of the following examples. Here we revert the color
+of the note head to the default value for the final two notes:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+c d
+\override NoteHead #'color = #red
+e f g
+\override NoteHead #'color = #green
+a
+\revert NoteHead #'color
+b c
+@end lilypond
+
+@strong{\once prefix}
+
+Both the @code{\override} and the @code{\set} commands may be
+prefixed by @code{\once}. This causes the following
+@code{\override} or @code{\set} command to be effective only
+during the current musical moment before the property reverts
+back to its default value. Using the same example, we can
+change the color of a single note like this:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+c d
+\once \override NoteHead #'color = #red
+e f g
+\once \override NoteHead #'color = #green
+a b c
+@end lilypond
-There is another form of the override command,
+@strong{\overrideProperty command}
+
+@cindex overrideProperty command
+@funindex \overrideProperty
+
+There is another form of the override command,
@code{\overrideProperty}, which is occasionally required.
-We mention it here for completeness, but for details see
+We mention it here for completeness, but for details see
@ruser{Difficult tweaks}.
@c Maybe explain in a later iteration -td
+@strong{\tweak command}
+
+@cindex tweak command
+@funindex \tweak
+
The final tweaking command which is available is @code{\tweak}.
This should be used to change the properties of objects which
occur at the same musical moment, such as the notes within a
chord. Using @code{\override} would affect all the notes
within a chord, whereas @code{\tweak} affects just the following
-item in the input stream. You may find the details in
+item in the input stream.
+
+Here's an example. Suppose we wish to change the size of the
+middle note (the E) in a C major chord. Let's first see what
+@code{\once \override} would do:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+ <c e g>4
+ \once \override NoteHead #'font-size = #-3
+ <c e g>
+ <c e g>
+@end lilypond
+
+We see the override affects @emph{all} the notes in the chord.
+This is because all the notes of a chord occur at the same
+@emph{musical moment}, and the action of @code{\once} is to
+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). Furthermore, when it is applied
+to note heads these @emph{must} be within a chord, i.e., within
+single angle brackets, so to tweak a single note the @code{\tweak}
+command must be placed inside single angle brackets with the
+note.
+
+So to return to our example, the size of the middle note of
+a chord would be changed in this way:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+ <c e g>4
+ <c \tweak #'font-size #-3 e g>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. So the general syntax of the
+@code{\tweak} command is simply:
+
+@example
+\tweak #'@emph{layout_property} = #@emph{value}
+@end example
+
+A @code{\tweak} command can also be used to modify just one in
+a series of articulations, as shown here:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+a ^Black
+ -\tweak #'color #red ^Red
+ -\tweak #'color #green _Green
+@end lilypond
+
+Note that the @code{\tweak} command must be preceded by an
+articulation mark as if it were an articulation itself.
+
+@cindex tuplets, nested
+@cindex triplets, nested
+@cindex bracket, tuplet
+@cindex tuplet bracket
+@cindex triplet bracket
+@funindex TupletBracket
+
+The @code{\tweak} command must also be used to change the
+appearance of one of a set of nested tuplets which begin at the
+same musical moment. In the following example, the long tuplet
+bracket and the first of the three short brackets begin at the
+same musical moment, so any @code{\override} command would apply
+to both of them. In the example, @code{\tweak} is used to
+distinguish between them. The first @code{\tweak} command
+specifies that the long tuplet bracket is to be placed above the
+notes and the second one specifies that the tuplet number is to be
+printed in red on the first short tuplet bracket.
+
+@lilypond[quote,ragged-right,verbatim,fragment,relative=2]
+\tweak #'direction #up
+\times 4/3 {
+ \tweak #'color #red
+ \times 2/3 { c8[ c8 c8] }
+ \times 2/3 { c8[ c8 c8] }
+ \times 2/3 { c8[ c8 c8] }
+}
+@end lilypond
+
+You can find more details of the @code{\tweak} command in
@ruser{Objects connected to the input}.
+If nested tuplets do not begin at the same moment their
+appearance may be modified in the usual way with
+@code{\override} commands:
+
+@c NOTE Tuplet brackets collide if notes are high on staff
+@c See issue 509
+@lilypond[quote,ragged-right,verbatim,fragment,relative=1]
+\times 2/3 { c8[ c c]}
+\once \override TupletNumber
+ #'text = #tuplet-number::calc-fraction-text
+\times 2/3 {
+ c[ c]
+ c[ c]
+ \once \override TupletNumber #'transparent = ##t
+ \times 2/3 { c8[ c c] }
+\times 2/3 { c8[ c c]}
+}
+@end lilypond
+
+
@node The Internals Reference manual
@section The Internals Reference manual
{
\time 6/8
{
- r4 b8 b[( g]) g |
- g[( e]) e d[( f]) a |
+ r4 b8 b[( g]) g |
+ g[( e]) e d[( f]) a |
a g
}
\addlyrics {
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
at first, so we can be sure the command is working. We get:
@example
- \override Slur #'thickness = #5.0
+\override Slur #'thickness = #5.0
@end example
Don't forget the @code{#'} preceding the
a g
}
\addlyrics {
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
r4 b8
% Increase thickness of immediately following slur only
\once \override Slur #'thickness = #5.0
- b[( g]) g |
- g[( e]) e d[( f]) a |
- a g
+ b[( g]) g |
+ g[( e]) e d[( f]) a |
+ a g
}
\addlyrics {
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
@noindent
Now only the first slur is made heavier.
-The @code{\once} command can also be used before @code{\set}
-and @code{\unset}, and before the command to be introduced
-in the following section -- @code{revert}.
-
+The @code{\once} command can also be used before the @code{\set}
+command.
+
@subheading Reverting
@cindex revert
b[( g]) g |
% Increase thickness of immediately following slur only
\once \override Slur #'thickness = #5.0
- g[( e]) e d[( f]) a |
+ g[( e]) e d[( f]) a |
a g
}
\addlyrics {
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
% Increase thickness of all following slurs from 1.2 to 5.0
\override Slur #'thickness = #5.0
b[( g]) g |
- g[( e])
+ g[( e])
% Revert thickness of all following slurs to default of 1.2
\revert Slur #'thickness
- e d[( f]) a |
+ e d[( f]) a |
a g
}
\addlyrics {
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
including @code{font-shape(symbol)}, where @code{symbol} can be
set to @code{upright}, @code{italics} or @code{caps}.
-You will notice that that @code{font-series} and @code{font-size}
+You will notice that @code{font-series} and @code{font-size}
are also listed there.
This immediately raises the question: Why are the common font
properties @code{font-series} and @code{font-size} listed under
@code{LyricText} then tell you the values for those two
properties which apply to @code{LyricText}. Other objects
which support @code{font-interface} will set these
-properties diferently when they are created.
+properties differently when they are created.
Let's see if we can now construct the @code{\override} command
to change the lyrics to italics. The object is @code{LyricText},
LilyPond. Some of them are the names of properties,
like @code{thickness} or @code{font-shape}, others are in
effect special values that can be given to properties, like
-@code{italic}. Note the distinction from arbitary
+@code{italic}. Note the distinction from arbitrary
text strings, which would appear as @code{"a text string"}.
Ok, so the @code{\override} command we need to print the lyrics
in italics should be
@example
- \override LyricText #'font-shape = #'italic
+\override LyricText #'font-shape = #'italic
@end example
@noindent
}
\addlyrics {
\override LyricText #'font-shape = #'italic
- The man who feels love's sweet e -- mo -- tion
+ The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
@noindent
and the lyrics are all printed in italics.
-@subheading Specifying context in lyric mode
+@subheading Specifying the context in lyric mode
@cindex context, specifying in lyric mode
In the case of lyrics, if you try specifying the context in the
spaces must be inserted before and after the
period or dot, @q{.}, separating the context name from the
object name, as otherwise the two names are run together and
-the interpreter cannot recognise them. So the command should be:
+the interpreter cannot recognize them. So the command should be:
@example
- \override Lyrics . LyricText #'font-shape = #'italic
+\override Lyrics . LyricText #'font-shape = #'italic
@end example
@warning{In lyrics always leave whitespace between the final
@tab @code{2.5}, @code{0.34}
@item Direction
@tab A valid direction constant or its numerical equivalent
- @tab @code{#LEFT}, @code{#CENTER}, @code{#UP},
+ @tab @code{LEFT}, @code{CENTER}, @code{UP},
@code{1}, @code{-1}
@item Integer
@tab A positive whole number
@node Appearance of objects
@section Appearance of objects
-Let us now put what we have learnt into practice with a few
+Let us now put what we have learned into practice with a few
examples which show how tweaks may be used to change the
appearance of the printed music.
requires is actually a list of values in internal units,
but, to avoid having to know what these are, several ways
are provided to specify colors. The first way is to use one
-of the @q{normal} colours listed in the first table in
+of the @q{normal} colors listed in the first table in
@ruser{List of colors}. To set the bar lines to white
we write:
<<
{ f c c }
\new Staff \with {
- alignAboveContext = "main"
+ alignAboveContext = "main"
}
{
\override Staff.Clef #'stencil = ##f
@noindent
where the extra pair of braces after the @code{\with} clause are
-required to ensure the enclosed overrrides and music are applied
+required to ensure the enclosed overrides and music are applied
to the ossia staff.
But what is the difference between modifying the staff context by
context is created, and remain in force as the @strong{default}
values for the duration of that context, whereas
@code{\set} or @code{\override} commands embedded in the
-music are dynamic -- they make changes synchronised with
+music are dynamic -- they make changes synchronized with
a particular point in the music. If changes are unset or
reverted using @code{\unset} or @code{\revert} they return to
their default values, which will be the ones set in the
<<
{ f c c }
\new Staff \with {
- alignAboveContext = "main"
+ alignAboveContext = "main"
% Don't print clefs in this staff
\override Clef #'stencil = ##f
% Don't print time signatures in this staff
<<
{ f c c }
\new Staff \with {
- alignAboveContext = "main"
+ alignAboveContext = "main"
\override Clef #'stencil = ##f
\override TimeSignature #'stencil = ##f
% Reduce all font sizes by ~24%
<<
{ f c c }
\new Staff \with {
- alignAboveContext = "main"
+ alignAboveContext = "main"
\override Clef #'stencil = ##f
\override TimeSignature #'stencil = ##f
fontSize = #-2
value of the @code{staff-space} property these are automatically
scaled down in length too. Note that this affects only the
vertical scale of the ossia -- the horizontal scale is determined
-by the layout of the main music in order to remain synchronised
+by the layout of the main music in order to remain synchronized
with it, so it is not affected by any of these changes in size.
Of course, if the scale of all the main music were changed in this
way then the horizontal spacing would be affected. This is
@section Placement of objects
@menu
-* Automatic behaviour::
+* Automatic behavior::
* Within-staff objects::
* Outside staff objects::
@end menu
-@node Automatic behaviour
-@subsection Automatic behaviour
+@node Automatic behavior
+@subsection Automatic behavior
There are some objects in musical notation that belong to
the staff and there are other objects that should be
tied to other objects that are so positioned. Collisions of
note heads, stems and accidentals in closely set chords are
normally avoided automatically. There are commands and
-overrides which can modify this automatic behaviour, as we
+overrides which can modify this automatic behavior, as we
shall shortly see.
Objects belonging outside the staff include things such as
placed closer to the staff.
In the following example all the markup texts have the same
-priority (since it is not explicity set). Note that @q{Text3}
+priority (since it is not explicitly set). Note that @q{Text3}
is automatically positioned close to the staff again, nestling
under @q{Text2}.
These commands are essential when writing polyphonic music to
permit interweaving melodic lines to be distinguished.
But occasionally it may be necessary to override this automatic
-behaviour. This can be done for whole sections of music or even
+behavior. This can be done for whole sections of music or even
for an individual note. The property which controls this
-behaviour is the @code{direction} property of each layout object.
+behavior is the @code{direction} property of each layout object.
We first explain what this does, and then introduce a number of
ready-made commands which avoid your having to code explicit
overrides for the more common modifications.
right or left when they point up or down. This is controlled
automatically when @code{direction} is set.
-The following example shows in bar 1 the default behaviour of
+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 behaviour.
+reverted back to the default behavior.
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
a4 g c a
Here is a table of the commonest. The meaning of each is stated
where it is not obvious.
-@multitable @columnfractions .2 .2 .2 .4
-@headitem Down/Left
+@multitable @columnfractions .2 .2 .25 .35
+@headitem Down/Left
@tab Up/Right
@tab Revert
@tab Effect
to the left (if @code{left} appears, or to the right
(if @code{right} appears). Conversely, if a location is not
listed, no fingering is placed there. LilyPond takes these
-contraints and works out the best placement for the fingering
+constraints and works out the best placement for the fingering
of the notes of the following chords. Note that @code{left} and
@code{right} are mutually exclusive -- fingering may be placed
only on one side or the other, not both.
@item @code{BarNumber} @tab @code{ 100}
@end multitable
-If the default values of @code{outside-staff-priority} does not
+If the default values of @code{outside-staff-priority} do not
give you the placing you want, the priority of any of the objects
may be overridden. Suppose we would
like the ottava bracket to be placed below the text spanner in the
control the vertical placement of individual objects, although
the results may not always be desirable. Suppose we would
like @qq{Text3} to be placed above @qq{Text4} in the example
-under Automatic behaviour, above (see @ref{Automatic behaviour}).
+under Automatic behavior, above (see @ref{Automatic behavior}).
All we need to do is to look up the priority of @code{TextScript}
in the IR or in the tables above, and increase the priority of
@qq{Text3} to a higher value:
By default, text produced by markup takes up no horizontal space
as far as laying out the music is concerned. The @code{\textLengthOn}
-command reverses this behaviour, causing the notes to be spaced
+command reverses this behavior, causing the notes to be spaced
out as far as is necessary to accommodate the text:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
c^"Text4"
@end lilypond
-The command to revert to the default behaviour is
+The command to revert to the default behavior is
@code{\textLengthOff}. Remember @code{\once} only works with
@code{\override}, @code{\set}, @code{\revert} or @code{unset},
so cannot be used with @code{\textLengthOn}.
% Turn off collision avoidance
\once \override TextScript #'outside-staff-priority = ##f
\textLengthOn % and turn on textLengthOn
-c,,2^"Long Text " % Spaces at end are honoured
+c,,2^"Long Text " % Spaces at end are honored
c''2
@end lilypond
aesthetic reasons -- they would look better with a little more
or a little less space around them.
-There are three main main approaches to resolving overlapping
+There are three main approaches to resolving overlapping
notation. They should be considered in the following order:
@enumerate
other objects will be moved automatically if necessary to make
room and (b) the single override can apply to all instances of
the same type of object. Such properties include:
+
@itemize
@item
Instead of @code{padding}, the placement of groups of accidentals
is controlled by @code{left-padding} and @code{right-padding}.
These properties are to be found in the @code{AccidentalPlacement}
-object which, note, lives in the @strong{staff} context. Because
-accidentals are always positioned after and to the left of
-note heads only the @code{right-padding} property has any effect.
+object which, note, lives in the @strong{staff} context. In the
+type-setting process the note heads are type-set first and then
+the accidentals, if any, are added to the left of the note heads
+using the @code{right-padding} property to determine the separation
+from the note heads. So only the @code{right-padding} property of the
+@code{AccidentalPlacement} object has any effect on the placement
+of the accidentals.
The @code{staff-padding} property is closely related to the
@code{padding} property: @code{padding}
@code{self-alignment-X}
@cindex self-alignment-X property
-This property can be used to align the object to the left, to
+This property can be used to align the object to the left, to
the right, or to center it with respect to the parent object's
reference point. It may be used with all objects which support
the @code{self-alignment-interface}. In general these are objects
to the leftmost extent and the second is added to the rightmost
extent. Negative numbers move the edge to the left, positive to
the right, so to widen an object the first number must be negative,
-the second positive. Note that not all objects honour both
+the second positive. Note that not all objects honor both
numbers. For example, the @code{Accidental} object only takes
notice of the first (left edge) number.
@cindex force-hshift property
-Closely spaced notes in a chord, or notes occuring at the same
+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
@end itemize
-Objects do not all have all of these properties in general.
-It is necessary to go to the IR to look up which properties
-are available for the object in question.
-
@item
Finally, when all else fails, objects may be manually repositioned
-relative to the staff center line verically, or by
+relative to the staff center line vertically, or by
displacing them by any distance to a new position. The
disadvantages are that the correct values for the repositioning
have to be worked out, often by trial and error, for every object
requested positions is selected from the list.
@end table
-Objects do not all have all of these properties in general.
+@end enumerate
+
+A particular object may not have all of these properties.
It is necessary to go to the IR to look up which properties
are available for the object in question.
-@end enumerate
-
Here is a list of the objects which are most likely to be
involved in collisions, together with the name of the object which
should be looked up in the IR in order to discover which properties
Let's now see how the properties in the previous section can
help to resolve overlapping notation.
-@subheading @code{padding} property
+@subheading padding property
@cindex padding property
The @code{padding} property can be set to increase
object
is handled in the @code{Score} context, property changes in the
@code{Voice} context will not be noticed. For more details, see
-@ruser{Constructing a tweak}.
+@ruser{Modifying properties}.
If the @code{padding} property of an object is increased when that
object is in a stack of objects being positioned according to
-their @code{outside-staff-priority}, then that object and all
+their @code{outside-staff-priority}, then that object and all
objects outside it are moved.
-
-@subheading left-padding and right-padding properties
+
+@subheading left-padding and right-padding
@cindex left-padding property
@cindex right-padding property
-TODO Example showing the utility of these properties -td
+The @code{right-padding} property affects the spacing between the
+accidental and the note to which it applies. It is not often
+required, but the following example shows one situation where it
+is needed. Suppose we wish to show a chord containing both
+a B-natural and a B-flat. To avoid ambiguity we would like to
+precede the notes with both a natural and a flat sign. Here
+are a few attempts to do this:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+<b bes>
+<b! bes>
+<b? bes>
+@end lilypond
+
+None work, with the second two showing bad collisions between
+the two signs.
+
+One way of achieving this is to override the accidental stencil
+with a markup containing the natural and flat symbols in the
+order we would like, like this:
+
+@lilypond[quote,ragged-right,verbatim]
+naturalplusflat = \markup { \natural \flat }
+\relative c'' {
+ \once \override Accidental
+ #'stencil = #ly:text-interface::print
+ \once \override Accidental #'text = #naturalplusflat
+ \once \override Score.AccidentalPlacement #'right-padding = #1.5
+ <b bes>
+}
+@end lilypond
+
+@noindent
+This necessarily uses an override for the accidental stencil which
+will not be covered until later. The stencil type must be a
+procedure, here changed to print the contents of the @code{text}
+property of @code{Accidental}, which itself is set to be a natural
+sign followed by a flat sign. These are then moved further away
+from the note head by overriding @code{right-padding}.
+
+@noindent
@subheading staff-padding property
@cindex staff-padding property
@end lilypond
-@subheading force-hshift property
-@cindex force-hshift property
-@c FIXME: formatting stuff (ie not important right now IMO)
-@c @a nchor Chopin finally corrected TODOgp
-
-We can now see how to apply the final corrections to the Chopin
-example introduced at the end of @ref{I'm hearing Voices}, which
-was left looking like this:
-
-@lilypond[quote,verbatim,fragment,ragged-right]
-\new Staff \relative c'' {
- \key aes \major
- <<
- { c2 aes4. bes8 } \\
- { aes2 f4 fes } \\
- { \voiceFour
- <ees c>2
- des2
- }
- >> |
- <c ees aes c>1 |
-}
-@end lilypond
-
-@noindent
-The lower two notes of the first chord (i.e,
-those in the third voice) should not be shifted away from the
-note column of the higher two notes. To correct this we set
-@code{force-hshift}, which is a property of
-@code{NoteColumn}, of these notes to zero.
-The lower note of the second chord is best placed just to the
-right of the higher notes. We achieve this by setting
-@code{force-hshift} of this note to 0.5, ie half a note head's
-width to the right of the note column of the higher notes.
-
-Here's the final result:
-
-@lilypond[quote,verbatim,fragment,ragged-right]
-\new Staff \relative c'' {
- \key aes \major
- <<
- { c2 aes4. bes8 } \\
- { aes2 f4 fes } \\
- { \voiceFour
- \once \override NoteColumn #'force-hshift = #0 <ees c>2
- \once \override NoteColumn #'force-hshift = #0.5 des2
- }
- >> |
- <c ees aes c>1 |
-}
-@end lilypond
-
-
@subheading positions property
@cindex positions property
@end lilypond
@noindent
-This can only be resolved by manually moving both ends of the beam
+This can be resolved by manually moving both ends of the beam
up from their position at 2 staff-spaces above the center line to,
say, 3:
the second block of quavers, but not to any of the beams in the
second voice.
+@subheading force-hshift property
+@cindex force-hshift property
+@c FIXME: formatting stuff (ie not important right now IMO)
+@c @a nchor Chopin finally corrected TODOgp
+
+We can now see how to apply the final corrections to the Chopin
+example introduced at the end of @ref{I'm hearing Voices}, which
+was left looking like this:
+
+@lilypond[quote,verbatim,fragment,ragged-right]
+\new Staff \relative c'' {
+ \key aes \major
+ <<
+ { c2 aes4. bes8 } \\
+ { aes2 f4 fes } \\
+ { \voiceFour
+ <ees c>2
+ des2
+ }
+ >> |
+ <c ees aes c>1 |
+}
+@end lilypond
+
+@noindent
+The lower two notes of the first chord (i.e,
+those in the third voice) should not be shifted away from the
+note column of the higher two notes. To correct this we set
+@code{force-hshift}, which is a property of
+@code{NoteColumn}, of these notes to zero.
+The lower note of the second chord is best placed just to the
+right of the higher notes. We achieve this by setting
+@code{force-hshift} of this note to 0.5, ie half a note head's
+width to the right of the note column of the higher notes.
+
+Here's the final result:
+
+@lilypond[quote,verbatim,fragment,ragged-right]
+\new Staff \relative c'' {
+ \key aes \major
+ <<
+ { c2 aes4. bes8 } \\
+ { aes2 f4 fes } \\
+ { \voiceFour
+ \once \override NoteColumn #'force-hshift = #0 <ees c>2
+ \once \override NoteColumn #'force-hshift = #0.5 des2
+ }
+ >> |
+ <c ees aes c>1 |
+}
+@end lilypond
+
+
@node Real music example
@subsection Real music example
engraving process, so please do not let these difficulties put
you off! Fortunately, difficulties like these are not very common!
-The example is from Chopin's Première Ballade, Op. 23, bars 6 to
+The example is from Chopin's Première Ballade, Op. 23, bars 6 to
9, the transition from the opening Lento to Moderato.
Here, first, is what we want the output to look like, but to avoid
over-complicating the example too much we have left out the
index in the Notation Reference does not mention merging,
but a search of the text for @q{merge} quickly leads us to
the overrides for merging differently headed and differently
-dotted notes in @ruser{Collision Resolution}. In our
+dotted notes in @ruser{Collision resolution}. In our
example we need to merge both types of note for the duration
of the polyphonic section in bar 3, so using the information
in the Notation Reference we add
The C is in voice two which has shift off, and the two D's are in
voices one and three, which have shift off and shift on,
respectively. So we have to shift the C a further level still
-using @code{\shiftOnn} to avoid it interferring with the two D's.
+using @code{\shiftOnn} to avoid it interfering with the two D's.
Applying these changes gives:
@lilypond[quote,verbatim,ragged-right]
* Other uses for tweaks::
* Using variables for tweaks::
* Other sources of information::
-* Advanced tweaks with Scheme::
* Avoiding tweaks with slower processing::
+* Advanced tweaks with Scheme::
@end menu
@node Other uses for tweaks
@subsection Other uses for tweaks
-@itemize
-
-@cindex transparent property
+@cindex transparent property, use of
@cindex objects, making invisible
@cindex removing objects
@cindex objects, removing
@cindex hiding objects
@cindex invisible objects
+@cindex tying notes across voices
-@item
-Setting the @code{transparent} property will cause an object
-to be printed in @q{invisible ink}: the object is not printed,
-but all its other behavior is retained. The object still takes
-up space, it takes part in collisions, and slurs, ties, and beams
-can be attached to it.
+@subheading Tying notes across voices
-The following example demonstrates how to connect different voices
-using ties. Normally, ties only connect two notes in the same
-voice. By introducing a tie in a different voice,
+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
@lilypond[quote,fragment,relative=2]
-<< {
- b8~ b8\noBeam
-} \\ {
- b[ g8]
-} >>
+<< { b8~ b8\noBeam }
+\\ { b[ g8] }
+>>
@end lilypond
@noindent
-and blanking the first up-stem in that voice, the tie appears to cross
-voices:
+and blanking the first up-stem in that voice, the tie appears to
+cross voices:
@lilypond[quote,fragment,relative=2,verbatim]
-<< {
- \once \override Stem #'transparent = ##t
- b8~ b8\noBeam
-} \\ {
- b[ g8]
-} >>
+<<
+ {
+ \once \override Stem #'transparent = ##t
+ b8~ b8\noBeam
+ }
+\\
+ { b[ g8] }
+>>
@end lilypond
-To make sure that the just-blanked stem doesn't squeeze the tie too much,
-we also lengthen the stem, by setting the @code{length} to
-@code{8},
+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},
@lilypond[quote,fragment,relative=2,verbatim]
-<< {
- \once \override Stem #'transparent = ##t
- \once \override Stem #'length = #8
- b8~ b8\noBeam
-} \\ {
- b[ g8]
-} >>
+<<
+ {
+ \once \override Stem #'transparent = ##t
+ \once \override Stem #'length = #8
+ b8~ b8\noBeam
+ }
+\\
+ { b[ g8] }
+>>
@end lilypond
-@cindex stencil property
+@subheading Simulating a fermata
+
+@cindex stencil property, use of
+@cindex fermata, implementing in MIDI
-@item
For outside-staff objects it is usually better to override the
object's @code{stencil} property rather than its @code{transparent}
-property when you wish to remove it from the printed output.
+property when you wish to remove it from the printed output.
Setting the @code{stencil} property of an object to @code{#f} will
remove that object entirely from the printed output. This means it
has no effect on the placement of other objects placed relative to
For example, if we wished to change the metronome setting in order
to simulate a fermata in the MIDI output we would not want the
-metronome marking to appear in the printed output, and we would
+metronome markings to appear in the printed output, and we would
not want it to influence the spacing between the two systems or
-the spacing of the notes on the staff. So setting its
-@code{stencil} property to @code{#f} would be the best way.
+the positions of adjacent annotations on the staff. So setting
+its @code{stencil} property to @code{#f} would be the best way.
We show here the effect of the two methods:
-@lilypond[quote,verbatim]
+@lilypond[quote,verbatim,ragged-right]
\score {
\relative c'' {
% Visible tempo marking
\tempo 4=120
a4 a a
\once \override Score.MetronomeMark #'transparent = ##t
- % Invisible tempo marking to lengthen fermata note in MIDI
+ % Invisible tempo marking to lengthen fermata in MIDI
\tempo 4=80
a\fermata
- \once \override Score.MetronomeMark #'stencil = ##f
- % Invisible tempo marking to restore tempo in MIDI
+ % New tempo for next section
+ \tempo 4=100
+ a a a a
+ }
+ \layout { }
+ \midi { }
+}
+@end lilypond
+
+@lilypond[quote,verbatim,ragged-right]
+\score {
+ \relative c'' {
+ % Visible tempo marking
\tempo 4=120
+ a4 a a
+ \once \override Score.MetronomeMark #'stencil = ##f
+ % Invisible tempo marking to lengthen fermata in MIDI
+ \tempo 4=80
+ a\fermata
+ % New tempo for next section
+ \tempo 4=100
a a a a
}
+ \layout { }
\midi { }
}
@end lilypond
@noindent
-Both methods remove the metronome mark from the printed output,
-and both affect the MIDI timing as required, but the first
-(transparent) metronome mark still influences the note spacing
-while the second (with no stencil) does not.
-
-@end itemize
+Both methods remove the metronome mark which lengthens the fermata
+from the printed output, and both affect the MIDI timing as
+required, but the transparent metronome mark in the first line
+forces the following tempo indication too high while the
+second (with the stencil removed) does not.
@node Using variables for tweaks
@subsection Using variables for tweaks
-TODO Add section
+Override commands are often long and tedious to type, and they
+have to be absolutely correct. If the same overrides are to be
+used many times it may be worth defining variables to hold them.
+Suppose we wish to emphasize certain words in lyrics by printing
+them in bold italics. The @code{\italic} and @code{\bold}
+commands do not work within lyrics so we must instead use the
+following @code{\override} and @code{\revert} commands:
+
+@example
+@code{\override Lyrics . LyricText #'font-shape = #'italic}
+@code{\override Lyrics . LyricText #'font-series = #'bold}
+
+@code{\revert Lyrics . LyricText #'font-shape}
+@code{\revert Lyrics . LyricText #'font-series}
+@end example
+
+These would be extremely tedious to enter if there were many words
+requiring emphasis. So instead we define these as two variables,
+and use them as follows:
+
+@lilypond[quote,verbatim]
+emph = {
+ \override Lyrics . LyricText #'font-shape = #'italic
+ \override Lyrics . LyricText #'font-series = #'bold
+}
+norm = {
+ \revert Lyrics . LyricText #'font-shape
+ \revert Lyrics . LyricText #'font-series
+}
+
+global = { \time 4/4 \partial 4 \key c \major}
+SopMusic = \relative c' { c4 | e4. e8 g4 g | a a g }
+AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e }
+TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 }
+BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 }
+VerseOne = \lyrics { E -- | ter -- nal \emph Fa -- ther, \norm | strong to save, }
+VerseTwo = \lyricmode { O | \emph Christ, \norm whose voice the | wa -- ters heard, }
+VerseThree = \lyricmode { O | \emph Ho -- ly Spi -- rit, \norm | who didst brood }
+VerseFour = \lyricmode { O | \emph Tri -- ni -- ty \norm of | love and pow'r }
+
+\score {
+ \new ChoirStaff <<
+ \new Staff <<
+ \clef "treble"
+ \new Voice = "Sop" { \voiceOne \global \SopMusic }
+ \new Voice = "Alto" { \voiceTwo \AltoMusic }
+ \new Lyrics \lyricsto "Sop" { \VerseOne }
+ \new Lyrics \lyricsto "Sop" { \VerseTwo }
+ \new Lyrics \lyricsto "Sop" { \VerseThree }
+ \new Lyrics \lyricsto "Sop" { \VerseFour }
+ >>
+ \new Staff <<
+ \clef "bass"
+ \new Voice = "Tenor" { \voiceOne \TenorMusic }
+ \new Voice = "Bass" { \voiceTwo \BassMusic }
+ >>
+ >>
+}
+@end lilypond
+
+
@node Other sources of information
@subsection Other sources of information
The Internals Reference documentation contains a lot of information
-about LilyPond, but even more information can be gathered from
-looking at the internal LilyPond files.
+about LilyPond, but even more information can be gathered by
+looking at the internal LilyPond files. To explore these, you must
+first find the directory appropriate to your system. The location
+of this directory depends (a) on whether you obtained LilyPond
+by downloading a precompiled binary from lilypond.org
+or whether you installed it from a package manager (i.e.
+distributed with Linux, or installed under fink or cygwin) or
+compiled it from source, and (b) on which operating system it is
+being used:
-TODO Show example, then explain where to find ly/propert-ly.
+@strong{Downloaded from lilypond.org}
-Some default settings (such as the definitions for
-@code{\header@{@}}s) are stored as @code{.ly} files. Other
-settings (such as the definitions of markup commands) are
-stored as @code{.scm} (Scheme) files. Further explanation is
-outside the scope of this manual; users should be warned that
-a substantial amount of technical knowledge or time is required
-to understand these files.
+@itemize @bullet
+@item Linux
-@itemize
+Navigate to
+@file{@var{INSTALLDIR}/lilypond/usr/share/lilypond/current/}
-@item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
+@item MacOS X
-@item OSX:
-@file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
-To access this, either @code{cd} into this directory from the
-Terminal, or control-click on the LilyPond application and select
-@q{Show Package Contents}.
+Navigate to
+@file{@var{INSTALLDIR}/LilyPond.app/Contents/Resources/share/lilypond/current/}
+by either @code{cd}-ing into this directory from the
+Terminal, or control-clicking on the LilyPond application and
+selecting @q{Show Package Contents}.
-@item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
+@item Windows
-@end itemize
+Using Windows Explorer, navigate to
+@file{@var{INSTALLDIR}/LilyPond/usr/share/lilypond/current/}
-The @file{ly/} and @file{scm/} directories will be of
-particular interest. Files such as @file{ly/property-init.ly} and
-@file{ly/declarations-init.ly} define all the common tweaks.
+@end itemize
+@strong{Installed from a package manager or compiled from source}
-@node Advanced tweaks with Scheme
-@subsection Advanced tweaks with Scheme
+Navigate to
+@file{@var{PREFIX}/share/lilypond/@var{X.Y.Z}/}, where
+@var{PREFIX} is set by your package manager or @code{configure}
+script, and @var{X.Y.Z} is the LilyPond version number.
-We have seen how LilyPond output can be heavily modified using
-commands like
-@code{\override TextScript #'extra-offset = ( 1 . -1)}. But
-we have even more power if we use Scheme. For a full explantion
-of this, see the @ref{Scheme tutorial}, and
-@ruser{Interfaces for programmers}.
+@smallspace
-We can use Scheme to simply @code{\override} commands,
+Within this directory the two interesting subdirectories are
-TODO Check this is a valid example with skylining
-
-@lilypond[quote,verbatim,ragged-right]
-padText = #(define-music-function (parser location padding) (number?)
-#{
- \once \override TextScript #'padding = #$padding
-#})
-
-\relative c''' {
- c4^"piu mosso" b a b
- \padText #1.8
- c4^"piu mosso" d e f
- \padText #2.6
- c4^"piu mosso" fis a g
-}
-@end lilypond
-
-We can use it to create new commands,
+@itemize
+@item @file{ly/} - contains files in LilyPond format
+@item @file{scm/} - contains files in Scheme format
+@end itemize
-TODO Check this is a valid example with skylining
+Let's begin by looking at some files in @file{ly/}.
+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 built-in
+commands, such as @code{\stemUp} 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:
-@lilypond[quote,verbatim,ragged-right]
-tempoMark = #(define-music-function (parser location padding marktext)
- (number? string?)
-#{
- \once \override Score . RehearsalMark #'padding = $padding
- \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
- \mark \markup { \bold $marktext }
-#})
+@example
+tieDotted = @{
+ \override Tie #'dash-period = #0.75
+ \override Tie #'dash-fraction = #0.1
+@}
+@end example
-\relative c'' {
- c2 e
- \tempoMark #3.0 #"Allegro"
- g c
-}
-@end lilypond
+If you do not like the default values these built-in commands can
+be redefined easily, just like any other variable, at the
+head of your input file.
+
+The following are the most useful files to be found in
+@file{ly/}:
+
+@multitable @columnfractions .4 .6
+@headitem Filename
+ @tab Contents
+@item @file{ly/engraver-init.ly}
+ @tab Definitions of engraver Contexts
+@item @file{ly/paper-defaults.ly}
+ @tab Specifications of paper-related defaults
+@item @file{ly/performer-init.ly}
+ @tab Definitions of performer Contexts
+@item @file{ly/property-init.ly}
+ @tab Definitions of all common built-in commands
+@end multitable
-Even music expressions can be passed in.
+Other settings (such as the definitions of markup commands) are
+stored as @code{.scm} (Scheme) files. The Scheme programming
+language is used to provide a programmable interface into
+LilyPond internal operation. Further explanation of these files
+is currently outside the scope of this manual, as a knowledge of
+the Scheme language is required. Users should be warned that
+a substantial amount of technical knowledge or time is required
+to understand Scheme and these files (see @ref{Scheme tutorial}).
+
+If you have this knowledge, the Scheme files which may be of
+interest are:
+
+@multitable @columnfractions .4 .6
+@headitem Filename
+ @tab Contents
+@item @file{scm/auto-beam.scm}
+ @tab Sub-beaming defaults
+@item @file{scm/define-grobs.scm}
+ @tab Default settings for grob properties
+@item @file{scm/define-markup-commands.scm}
+ @tab Specify all markup commands
+@item @file{scm/midi.scm}
+ @tab Default settings for MIDI output
+@item @file{scm/output-lib.scm}
+ @tab Settings that affect appearance of frets, colors,
+ accidentals, bar lines, etc
+@item @file{scm/parser-clef.scm}
+ @tab Definitions of supported clefs
+@item @file{scm/script.scm}
+ @tab Default settings for articulations
+@end multitable
-@lilypond[quote,verbatim,ragged-right]
-pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
-#{
- $x e8 a b $y b a e
-#})
-
-\relative c''{
- \pattern c8 c8\f
- \pattern {d16 dis} { ais16-> b\p }
-}
-@end lilypond
@node Avoiding tweaks with slower processing
@subsection Avoiding tweaks with slower processing
-LilyPond can perform extra checks while it processes files. These
-commands will take extra time, but the result may require fewer
-manual tweaks.
+LilyPond can perform extra checks while it processes input files. These
+checks will take extra time to perform, but fewer manual tweaks
+may be required to obtain an acceptable result. If a text script
+or part of the lyrics extends over the margins these checks will
+compress that line of the score just enough to fit within the
+margins.
+
+To be effective under all circumstances these checks must be enabled
+by placing the overrides in a Score @code{\with} block, rather than
+in-line in music, as follows:
@example
-%% makes sure text scripts and lyrics are within the paper margins
-\override Score.PaperColumn #'keep-inside-line = ##t
-\override Score.NonMusicalPaperColumn #'keep-inside-line = ##t
+\new Score \with @{
+ % Makes sure text scripts and lyrics are within the paper margins
+ \override PaperColumn #'keep-inside-line = ##t
+ \override NonMusicalPaperColumn #'keep-inside-line = ##t
+@} @{
+ ..
+@}
@end example
-In some cases (see issue 246), this must be done before
-@code{\override} commands can be processed.
+@node Advanced tweaks with Scheme
+@subsection Advanced tweaks with Scheme
-@verbatim
-\new Score \with {
- \override PaperColumn #'keep-inside-line = ##t
- \override NonMusicalPaperColumn #'keep-inside-line = ##t
- } {
- ..
-}
-@end verbatim
+Although many things are possible with the @code{\override} and
+@code{\tweak} commands, an even more powerful way of modifying
+the action of LilyPond is available through a programmable
+interface to the LilyPond internal operation. Code written in
+the Scheme programming language can be incorporated directly in
+the internal operation of LilyPond. Of course, at least a basic
+knowledge of programming in Scheme is required to do this, and an
+introduction is provided in the @ref{Scheme tutorial}.
+
+As an illustration of one of the many possibilities, instead of
+setting a property to a constant it can be set to a Scheme
+procedure which is then called whenever that property is accessed
+by LilyPond. The property can then be set dynamically to a value
+determined by the procedure at the time it is called. In this
+example we color the note head in accordance with its position on
+the staff.
+@lilypond[quote,verbatim,ragged-right]
+#(define (color-notehead grob)
+ "Color the notehead according to its position on the staff."
+ (let ((mod-position (modulo (ly:grob-property grob 'staff-position) 7)))
+ (case mod-position
+ ;; Return rainbow colors
+ ((1) (x11-color 'red )) ; for C
+ ((2) (x11-color 'orange )) ; for D
+ ((3) (x11-color 'yellow )) ; for E
+ ((4) (x11-color 'green )) ; for F
+ ((5) (x11-color 'blue )) ; for G
+ ((6) (x11-color 'purple )) ; for A
+ ((0) (x11-color 'violet )) ; for B
+ )
+ )
+)
+
+\relative c' {
+ % Arrange to obtain color from color-notehead procedure
+ \override NoteHead #'color = #color-notehead
+ c2 c' |
+ b4 g8 a b4 c |
+ c,2 a' |
+ g1 |
+}
+\addlyrics {
+ Some -- where o -- ver the Rain -- bow, way up high,
+}
+@end lilypond
+Further examples showing the use of these programmable interfaces
+can be found in @ref{Tweaking with Scheme}.
projects / lilypond.git / blobdiff