configurable; virtually every fragment of output may be changed.
TODO: This chapter is still under development and this version is
-somewhat experimental; nothing is fixed. Don't translate yet!
+not yet complete. Don't translate yet!
that you may learn how to develop your own tweaks.
Before starting on this Chapter you may wish to review the section
-@ref{Contexts and engravers}, as Contexts, Engravers, and the
+@ref{Contexts and engravers}, as Contexts, Engravers, and the
Properties contained within them are fundamental to understanding
and constructing Tweaks.
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
+and add @strong{engravers}, in
@ref{Modifying context properties} and @ref{Adding
and removing engravers}. We now must meet one more command.
@emph{layout_object}, which is a member of the @emph{context}
context, to the value @emph{value}.
-The @emph{context} can be omitted (and usually is) when the
+The @emph{context} can be omitted (and usually is) when the
required context is unambiguously implied and is one of lowest
-level contexts, i.e., @code{Voice}, @code{ChordNames} or
-@code{Lyrics}, and we shall omit it in many of the following
+level contexts, i.e., @code{Voice}, @code{ChordNames} or
+@code{Lyrics}, and we shall omit it in many of the following
examples. We shall see later when it must be specified.
For now, don't worry about the @code{#'}, which must precede the
@end example
Again, just like @emph{context} in the @code{\override} command,
-@emph{context} is often not needed. It will be omitted
+@emph{context} is often not needed. It will be omitted
in many of the following examples.
There is another form of the override command,
-@code{\overrideProperty}, which is occasionally required.
+@code{\overrideProperty}, which is occasionally required.
We mention it here for completeness, but for details see
@ruser{Difficult tweaks}.
@c Maybe explain in a later iteration -td
The final tweaking command which is available is @code{\tweak}.
It is not really a new command but a shorthand for an
-@code{\override} command which must be used in a few special
+@code{\override} command which must be used in a few special
circumstances. Again, we shall not discuss or use it here.
You may find the details in
@ruser{Objects connected to the input}.
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
{
\time 6/8
- {
+ {
r4 b8 b[( g]) g |
g[( e]) e d[( f]) a |
a g
}
- \addlyrics {
+ \addlyrics {
The man who feels love's sweet e -- mo -- tion
}
}
The final question is, @q{Where should this command be
placed?} While you are unsure and learning, the best
-answer is, @q{Within the music, before the first slur and
+answer is, @q{Within the music, before the first slur and
close to it.} Let's do that:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
{
\time 6/8
- {
+ {
% Increase thickness of all following slurs from 1.2 to 5.0
\override Slur #'thickness = #5.0
r4 b8 b[( g]) g |
the @code{Slur_engraver} is in. Follow the link to the
@code{Slur_engraver} page. At the very bottom it tells
us that @code{Slur_engraver} is part of five Voice contexts,
-including the standard voice context, @code{Voice}, so our
+including the standard voice context, @code{Voice}, so our
guess was correct. And because @code{Voice} is one of the
lowest level contexts which is implied unambiguously by
the fact that we are entering notes, we can omit it in this
@cindex once override
@funindex \once
-As you can see, @emph{all} the slurs are thicker in the
+As you can see, @emph{all} the slurs are thicker in the
final example above. But what if we
wanted just the first slur to be thicker? This is achieved
with the @code{\once} command. Placed immediately before
immediately following note does not begin a slur the command
has no effect at all -- it is not remembered until a slur
is encountered, it is simply discarded. So the command with
-@code{\once} must be
+@code{\once} must be
repositioned as follows:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
{
\time 6/8
- {
+ {
r4 b8
% Increase thickness of immediately following slur only
\once \override Slur #'thickness = #5.0
g[( e]) e d[( f]) a |
a g
}
- \addlyrics {
+ \addlyrics {
The man who feels love's sweet e -- mo -- tion
}
}
g[( e]) e d[( f]) a |
a g
}
- \addlyrics {
+ \addlyrics {
The man who feels love's sweet e -- mo -- tion
}
}
@end lilypond
@noindent
-or we could omit the @code{\once} command and use the
+or we could omit the @code{\once} command and use the
@code{\revert} command
to return the @code{thickness} property to its default value
after the second slur:
e d[( f]) a |
a g
}
- \addlyrics {
+ \addlyrics {
The man who feels love's sweet e -- mo -- tion
}
}
This is because the shape property is one that is common to all
font objects, so, rather than including it in every layout
object, it is grouped together with other similar common
-properties and placed in an @strong{Interface}, the
+properties and placed in an @strong{Interface}, the
@code{font-interface}.
So now we need to learn how to find the properties of interfaces,
Look again at the IR page which describes LyricText. At the
bottom of the page is a list of clickable (in the html versions
of the IR) interfaces which LyricText supports. The list has
-seven items, including @code{font-interface}.
+seven items, including @code{font-interface}.
Clicking on this brings up the properties associated
with this interface, which are also properties of all the objects
which support it, including LyricText.
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} as well as under the interface
+@code{LyricText} as well as under the interface
@code{font-interface} but @code{font-shape} is not? The answer
is that @code{font-series} and @code{font-size} are changed
from their global default values when a @code{LyricText} object
-is created, but @code{font-shape} is not. The entries in
+is created, but @code{font-shape} is not. The entries in
@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
Let's see if we can now construct the @code{\override} command
to change the lyrics to italics. The object is @code{LyricText},
-the property is @code{font-shape} and the value is
+the property is @code{font-shape} and the value is
@code{italic}. As before, we'll omit the context.
As an aside, although it is an important one, note that because
@code{font-shape} are symbols they must be introduced with a
single apostrophe, @code{'}. That is why apostrophes
are needed before @code{thickness} in the earlier example
-and @code{font-shape}. These are both symbols too.
+and @code{font-shape}. These are both symbols too.
Symbols are special names which are known internally to
LilyPond. Some of them are the names of properties,
like @code{thickness} or @code{font-shape}, others are in
The type of property is always shown in brackets after the
property name in the IR. Here is a list of the types you may
need, together with the rules for that type, and some examples.
-You must always add a hash symbol, @code{#}, of course,
+You must always add a hash symbol, @code{#}, of course,
to the front of these values when they are entered in the
@code{\override} command.
@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
@item List
@tab A bracketed set of items separated by spaces,
preceded by an apostrophe
- @tab @code{'(left-edge staff-bar)}, @code{'(1)},
+ @tab @code{'(left-edge staff-bar)}, @code{'(1)},
@code{'(1.0 0.25 0.5)}
@item Markup
@tab Any valid markup
@item Moment
@tab A fraction of a whole note constructed with the
make-moment function
- @tab @code{(ly:make-moment 1 4)},
+ @tab @code{(ly:make-moment 1 4)},
@code{(ly:make-moment 3 8)}
@item Number
@tab Any positive or negative decimal value
@tab @code{'italic}, @code{'inside}
@item Unknown
@tab A procedure or @code{#f} (to cause no action)
- @tab @code{bend::print}, @code{ly:text-interface::print},
+ @tab @code{bend::print}, @code{ly:text-interface::print},
@code{#f}
@item Vector
@tab A list of three items enclosed in brackets and preceded
by a hash sign, @code{#}.
- @tab @code{#(#t #t #f)}
+ @tab @code{#(#t #t #f)}
@end multitable
@node Appearance of objects
we find there
is a layout object called @code{BarLine}. Its properties include
two that control its visibility: @code{break-visibility} and
-@code{stencil}. Barline also supports a number of interfaces,
-including the @code{grob-interface}, where we find the
+@code{stencil}. Barline also supports a number of interfaces,
+including the @code{grob-interface}, where we find the
@code{transparent} and the @code{color} properties. All
of these can affect the visibility of barlines (and, of course,
by extension, many other layout objects too.) Let's consider
@cindex break-visibility property
-We see from the @code{BarLine} properties in the IR that the
-@code{break-visibility} property requires a vector of three
+We see from the @code{BarLine} properties in the IR that the
+@code{break-visibility} property requires a vector of three
booleans.
These control respectively whether barlines are printed at
the end of a line, in the middle of lines, and at the beginning
of lines. For our example we want all barlines to be suppressed,
-so the value we need is @code{#(#f #f #f)}.
+so the value we need is @code{#(#f #f #f)}.
Let's try that, remembering
to include the @code{Staff} context. Note also that in writing
this value we have two hash signs before the opening bracket.
the @q{All layout objects} page in the IR to find the properties
of the @code{TimeSignature} layout object. This is produced by
the @code{Time_signature_engraver} which you can check also lives
-in the @code{Staff} context and also supports the
+in the @code{Staff} context and also supports the
@code{grob-interface}. So the command to make the time signature
transparent is:
the time signature should be. Maybe this is what is wanted for
an exercise for the student to fill it in, but in other
circumstances a gap might be undesirable. To remove it, the
-stencil for the time signature should be set to @code{#f}
+stencil for the time signature should be set to @code{#f}
instead:
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
Let us begin by looking again at the earlier example
see @ref{Nesting music expressions}) which showed
-how to introduce a new temporary staff, as in an @rglos{ossia}.
+how to introduce a new temporary staff, as in an @rglos{ossia}.
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
\new Staff ="main" {
a typeface font. These include noteheads, accidentals, markup,
clefs, time signatures, dynamics and lyrics.
Their size is changed by modifying the
-@code{font-size} property, as we shall shortly see. Other
+@code{font-size} property, as we shall shortly see. Other
layout objects such as slurs and ties -- in general, spanner
objects -- are drawn individually, so there is no
@code{font-size}
Then it sorts the outside-staff objects according to their
@code{outside-staff-priority}. The outside-staff objects are
taken one by one, beginning with the object with the lowest
-@code{outside-staff-priority}, and placed so that they do not
+@code{outside-staff-priority}, and placed so that they do not
collide with any objects that have already been placed. That is,
if two outside-staff grobs are competing for the same space, the
-one with the lower @code{outside-staff-priority} will be placed
+one with the lower @code{outside-staff-priority} will be placed
closer to the staff. If two objects have the same
@code{outside-staff-priority} the one encountered first will be
placed closer to the staff.
@headitem Down/Left
@tab Up/Right
@tab Revert
- @tab Effect
-@item \arpeggioDown
- @tab \arpeggioUp
- @tab \arpeggioNeutral
+ @tab Effect
+@item @code{\arpeggioDown}
+ @tab @code{\arpeggioUp}
+ @tab @code{\arpeggioNeutral}
@tab Arrow is at bottom, at top, or no arrow
-@item \dotsDown
- @tab \dotsUp
- @tab \dotsNeutral
+@item @code{\dotsDown}
+ @tab @code{\dotsUp}
+ @tab @code{\dotsNeutral}
@tab Direction of movement to avoid staff lines
-@item \dynamicDown
- @tab \dynamicUp
- @tab \dynamicNeutral
+@item @code{\dynamicDown}
+ @tab @code{\dynamicUp}
+ @tab @code{\dynamicNeutral}
@tab
-@item \phrasingSlurDown
- @tab \phrasingSlurUp
- @tab \phrasingSlurNeutral
+@item @code{\phrasingSlurDown}
+ @tab @code{\phrasingSlurUp}
+ @tab @code{\phrasingSlurNeutral}
@tab Note: distinct from slur commands
-@item \slurDown
- @tab \slurUp
- @tab \slurNeutral
+@item @code{\slurDown}
+ @tab @code{\slurUp}
+ @tab @code{\slurNeutral}
@tab
-@item \stemDown
- @tab \stemUp
- @tab \stemNeutral
+@item @code{\stemDown}
+ @tab @code{\stemUp}
+ @tab @code{\stemNeutral}
@tab
-@item \textSpannerDown
- @tab \textSpannerUp
- @tab \textSpannerNeutral
+@item @code{\textSpannerDown}
+ @tab @code{\textSpannerUp}
+ @tab @code{\textSpannerNeutral}
@tab Text entered as spanner is below/above staff
-@item \tieDown
- @tab \tieUp
- @tab \tieNeutral
+@item @code{\tieDown}
+ @tab @code{\tieUp}
+ @tab @code{\tieNeutral}
@tab
-@item \tupletDown
- @tab \tupletUp
- @tab \tupletNeutral
+@item @code{\tupletDown}
+ @tab @code{\tupletUp}
+ @tab @code{\tupletNeutral}
@tab Tuplets are below/above notes
@end multitable
-Note that these predefined commands may @strong{not} be
+Note that these predefined commands may @strong{not} be
preceded by @code{\once}. If you wish to limit the
effect to a single note you must either use the equivalent
@code{\once \override} command or use the predefined command
The property may be set to a list of one to three values.
It controls whether fingerings may be placed above (if
-@code{up} appears in the list), below (if @code{down} appears),
-to the left (if @code{left} appears, or to the right
+@code{up} appears in the list), below (if @code{down} appears),
+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
@subsection Outside staff objects
Outside-staff objects are automatically placed to avoid collisions.
-Objects with the lower value of @code{outside-staff-priority}
+Objects with the lower value of @code{outside-staff-priority}
property are placed nearer to the staff, and other outside-staff
objects are then raised as far as necessary to avoid collisions.
-The @code{outside-staff-priority} is defined in the
+The @code{outside-staff-priority} is defined in the
@code{grob-interface} and so is a property of all layout objects.
It is set to @code{#f} (the default) for all within-staff objects,
and is set explicitly to the default numerical value appropriate
@item @code{OttavaBracket} @tab @code{ 400}
@item @code{RehearsalMark} @tab @code{1500}
@item @code{TextScript} @tab @code{ 450}
+@item @code{TextSpanner} @tab @code{ 350}
@end multitable
TODO Add example showing iteraction of all these
@cindex notes, spreading out with text
By default, text produced by markup takes up no horizontal space
-as far as laying out the music is concerned. The @code{\fatText}
+as far as laying out the music is concerned. The @code{\fatText}
command reverses this behaviour, causing the notes to be spaced
out as far as is necessary to accommodate the text:
@end lilypond
@noindent
-Should a similar situation arise in @q{real} music, it may
+Should a similar situation arise in @q{real} music, it may
be preferable to space out the notes
a little further, so the dynamic markings can all fit at the
same vertical distance from the staff. We were able to do this
repositioned easily in this way. The limitation is that you
have a choice of only two positions, and neither may be
suitable.
+
@item
The @strong{object properties}, which LilyPond uses
when positioning layout objects, may be modified using
room and (b) the single override can apply to all instances of
the same type of object. Such properties include:
@itemize
-@item @code{direction}
+
+@item
+@code{direction}
This has already been covered in some detail -- see
@ref{Within-staff objects}.
-@item @code{padding}, @code{left-padding},
- @code{right-padding}, @code{staff-padding}
+
+@item
+@code{padding}, @code{left-padding},
+@code{right-padding}, @code{staff-padding}
@cindex left-padding property
@cindex padding property
@cindex right-padding property
@cindex staff-padding property
-The @code{padding} property specifies the gap that must be left
-between
-the top and bottom edges of objects which are positioned
-either above or below another previously placed object, or
-between the sides of objects which are positioned to the left or
-right of previously placed objects. @code{padding} can be applied
+As an object is being positioned the value of its @code{padding}
+property specifies the gap that must be left between itself and
+the nearest edge of the object against which it is being
+positioned. Note that it is the @code{padding} value of the object
+@strong{being placed} that is used;
+the @code{padding} value of the object which is already placed is
+ignored. Gaps specified by @code{padding} can be applied
to all objects which support the @code{side-position-interface}.
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.
+object which, note, lives in the @strong{staff} context. Because
+accidentals are always positioned after and to the left of
+noteheads only the @code{right-padding} property has any effect.
The @code{staff-padding} property is closely related to the
@code{padding} property: @code{padding}
(it varies with each object). It may be overridden if a larger
(or smaller) gap is required.
-@item @code{self-alignment-X}
+@item
+@code{self-alignment-X}
@cindex self-alignment-X property
This property aligns the object to the left, to the right, or
or @code{CENTER}. The movement is limited by the length of the
object. Any numerical value between @code{-1} and @code{+1} may
also be specified, where @code{-1} is left-aligned, @code{+1}
-is right-aligned, and numbers inbetween move the text progressively
-from left-aligned to right-aligned.
+is right-aligned, and numbers in between move the text
+progressively from left-aligned to right-aligned.
-@item @code{extra-spacing-width}
+@item
+@code{extra-spacing-width}
@cindex extra-spacing-width property
This property is available for all objects which support the
numbers. For example, the @code{Accidental} object only takes
notice of the first (left edge) number.
-@item @code{staff-position}
+@item
+@code{staff-position}
@cindex staff-position property
@code{staff-position} is a property of the
collisions between layout objects like multi-measure rests, ties
and notes in different voices.
-@item @code{force-hshift}
+@item
+@code{force-hshift}
@cindex force-hshift property
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
+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
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
approach is that the repositioning values may need to be reworked
if the music is later modified. The properties that can be used
for this type of manual repositioning are:
-@itemize
-@item @code{extra-offset}
+@table @code
+@item extra-offset
@cindex extra-offset property
This property applies to any layout object
supporting the @code{grob-interface}. It takes a pair of
finished, so an object may be repositioned anywhere without
affecting anything else.
-@item @code{positions}
-
+@item positions
@cindex positions property
This is most useful for manually adjusting the slope and height
of beams, slurs, and tuplets. It takes a pair of numbers
giving the position of the left and right ends of the beam, slur,
etc. relative to the center line of the staff. Units are
staff-spaces.
-
-@end itemize
+@end table
Objects do not all have all of these properties in general.
It is necessary to go to the IR to look up which properties
since the rest is in voice two.
The default in @code{\voiceTwo} (i.e. in the second voice of a
@code{<<@{...@} \\ @{...@}>>} construct)
-is that @code{staff-position} is set to -4 for MultiMeasureRest,
+is that @code{staff-position} is set to -4 for MultiMeasureRest,
so we need to move it, say, four half-staff spaces down to
@code{-8}.
The @code{positions} property allows the position and slope of
tuplets, slurs, phrasing slurs and beams to be controlled
manually. Here's an example which has an ugly phrasing slur
-due to it trying to avoid the slur on the acciaccatura.
+due to its trying to avoid the slur on the acciaccatura.
@lilypond[quote,verbatim,fragment,ragged-right,relative=1]
r4 \acciaccatura e8\( d8 c ~c d c d\)
@noindent
but if there were some reason why this could not be done the
other alternative would be to move the left end of the phrasing
-slur down a little using the @code{positions} property. This
+slur down a little using the @code{positions} property. This
also resolves the rather nasty shape.
@lilypond[quote,verbatim,fragment,ragged-right,relative=1]
of music takes.
Settings which influence layout may be placed in two blocks.
-The @code{\paper @{ ... @}} block is placed outside any
-@code{\score @{ ... @}} blocks and contains settings that
-relate to the entire document. The @code{\layout @{ ... @}}
-block is placed within a @code{\score @{ ... @}} block and
+The @code{\paper @{...@}} block is placed outside any
+@code{\score @{...@}} blocks and contains settings that
+relate to the entire document. The @code{\layout @{...@}}
+block is placed within a @code{\score @{...@}} block and
contains settings for that particular score. If you have
-only one @code{\score @{ ... @}} block the two have the same
+only one @code{\score @{...@}} block the two have the same
effect. In general the commands shown in this section can
be placed in either.
@node Global sizes
@subsection Global sizes
-The default @strong{paper size} which LilyPond assumes in laying
+TODO Check all these examples
+
+The default @strong{paper size} which LilyPond assumes in laying
out the music is A4. This may be changed in two ways:
@example
@noindent
The first command sets the size of all pages. The second command
-sets the size of the pages to which the \paper block applies \96 if
+sets the size of the pages to which the \paper block applies -\96 if
the \paper block is at the top of the file, then it will apply
-to all pages. Support for the following paper sizes are included:
+to all pages. Support for the following paper sizes is included:
a6, a5, a4, a3, legal, letter, 11x17 (also known as tabloid).
+Setting the paper size automatically sets suitable margins and
+line length.
If the symbol @code{landscape} is supplied as an argument to
@code{set-default-paper-size}, the pages will be rotated by 90
@subsection Line breaks
Line breaks are normally computed automatically. They are chosen
-so that lines look neither cramped nor loose, and that consecutive
+so that lines look neither cramped nor loose, and consecutive
lines have similar density. Occasionally you might want to
override the automatic breaks; you can do this by specifying
-@code{\break}. This will force a line break at this point. Line
-breaks can only occur at the end of @q{complete} bars, i.e., where
-there are no notes or tuplets left @q{hanging} over the bar line.
-If you want to have a line break where there is no bar line, you
-can force an invisible bar line by entering @code{\bar ""}.
-Similarly, @code{\noBreak} forbids a line break at a point.
-
-The most basic settings influencing line spacing are @code{indent}
-and @code{line-width}. They are set in the @code{\layout} block.
+@code{\break}. This will force a line break at this point. However,
+line breaks can only occur at the end of @q{complete} bars, i.e.,
+where there are no notes or tuplets left @q{hanging} over the bar
+line. If you want to have a line break where there is no bar line,
+you can force an invisible bar line by entering @code{\bar ""},
+although again there must be no notes left hanging over in any of
+the staves.
+
+The opposite command, @code{\noBreak}, forbids a line break at the
+bar line where it is inserted.
+
+The most basic settings influencing line spacing are @code{indent}
+and @code{line-width}. They are set in the @code{\layout} block.
They control the indentation of the first line of music, and the
lengths of the lines.
spacing is.
The option @code{ragged-last} is similar to @code{ragged-right},
-but only affects the last line of the piece.
+but affects only the last line of the piece.
@example
\layout @{
The default page breaking may be overriden by inserting
@code{\pageBreak} or @code{\noPageBreak} commands.
These commands are analogous to @code{\break} and @code{\noBreak}.
-These commands force and forbid a page-break from happening.
+These commands force and forbid a page-break at the point where
+they are inserted.
Of course, the @code{\pageBreak} command also forces a line break.
Like @code{\break}, the @code{\pageBreak} command is effective only
at the end of a @q{complete} bar as defined above. For more
details see @ruser{Page breaking} and following sections.
-There are also analogous settings to @code{ragged-right} and
+There are also analogous settings to @code{ragged-right} and
@code{ragged-last} which have the same effect on vertical spacing:
@code{ragged-bottom} and @code{ragged-last-bottom}. If set to
@code{##t} the systems on all pages or just the last page
+
projects / lilypond.git / commitdiff