1 @c -*- coding: utf-8; mode: texinfo; -*-
3 @chapter Tweaking output
9 * Fixing overlapping notation::
11 * Advanced tweaks with scheme::
15 @node Fixing overlapping notation
16 @section Fixing overlapping notation
18 This may come as a surprise, but LilyPond isn't perfect. Some notation
19 elements can overlap. This is unfortunate, but (in most cases) is easily
22 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
23 e4^\markup{ \italic ritenuto } g b e
28 The easiest solution is to increase the distance between the object
29 (in this case text, but it could easily be fingerings or dynamics
30 instead) and the note. In LilyPond, this is called the
31 @code{padding} property; it is measured in staff spaces. For most
32 objects, this value is around 1.0 or less (it varies with each
33 object). We want to increase it, so let's try 1.5
35 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
36 \once \override TextScript #'padding = #1.5
37 e4^\markup{ \italic ritenuto } g b e
40 That looks better, but it isn't quite big enough. After experimenting
41 with a few values, we think 2.3 is the best number in this case. However,
42 this number is merely the result of experimentation and my personal
43 taste in notation. Try the above example with 2.3... but also try higher
44 (and lower) numbers. Which do you think looks the best?
46 The @code{staff-padding} property is closely related. @code{padding}
47 controls the minimum amount of space between an object and the nearest
48 other object (generally the note or the staff lines);
49 @code{staff-padding} controls the minimum amount of space between an
50 object and the staff. This is a subtle difference, but you can see
53 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
55 \once \override TextScript #'padding = #2.6
57 \once \override TextScript #'staff-padding = #2.6
58 c4^"piu mosso" fis a g
60 c,,4^"piu mosso" b a b
61 \once \override TextScript #'padding = #2.6
63 \once \override TextScript #'staff-padding = #2.6
64 c4^"piu mosso" fis a g
69 Another solution gives us complete control over placing the object -- we
70 can move it horizontally or vertically. This is done with the
71 @code{extra-offset} property. It is slightly more complicated and can
72 cause other problems. When we move objects with @code{extra-offset},
73 the movement is done after LilyPond has placed all other objects. This means
74 that the result can overlap with other objects.
76 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
77 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
78 e4^\markup{ \italic ritenuto } g b e
81 With @code{extra-offset}, the first number controls the horizontal
82 movement (left is negative); the second number controls the vertical
83 movement (up is positive). After a bit of experimenting, we decided
84 that these values look good
86 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
87 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
88 e4^\markup{ \italic ritenuto } g b e
92 Again, these numbers are simply the result of a few experiments and
93 looking at the output. You might prefer the text to be slightly higher,
94 or to the left, or whatever. Try it and look at the result!
96 One final warning: in this section, we used
99 \once \override TextScript @dots{}
102 This tweaks the display of text for the next note. If the note has
103 no text, this tweak does nothing (and does @strong{not} wait until
104 the next bit of text).
106 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
108 \once \override TextScript #'padding = #2.6
111 \once \override TextScript #'padding = #2.6
115 \override TextScript #'padding = #2.6
123 This manual: @ref{The \override command}, @ref{Common tweaks}.
131 @section Common tweaks
133 @c Should we point at ly/property-init.ly ? -gp
134 Some overrides are so common that predefined commands are provided as
135 short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These
136 commands are described in
140 @c @ref{Notation manual},
143 under the sections for slurs and stems
146 The exact tuning possibilities for each type of layout object are
147 documented in the program reference of the respective
148 object. However, many layout objects share properties, which can be
149 used to apply generic tweaks. We mention a few of these:
152 @item The @code{extra-offset} property, which
153 @cindex @code{extra-offset}
154 has a pair of numbers as value, moves objects around in the printout.
155 The first number controls left-right movement; a positive number will
156 move the object to the right. The second number controls up-down
157 movement; a positive number will move it higher. The units of these
158 offsets are staff-spaces. The @code{extra-offset} property is a
159 low-level feature: the formatting engine is completely oblivious to
162 In the following example, the second fingering is moved a little to
163 the left, and 1.8 staff space downwards:
165 @cindex setting object properties
167 @lilypond[quote,fragment,relative=1,verbatim]
170 \once \override Fingering
171 #'extra-offset = #'(-0.3 . -1.8)
176 Setting the @code{transparent} property will cause an object to be printed
177 in `invisible ink': the object is not printed, but all its other
178 behavior is retained. The object still takes up space, it takes part in
179 collisions, and slurs, ties, and beams can be attached to it.
181 @cindex transparent objects
182 @cindex removing objects
183 @cindex hiding objects
184 @cindex invisible objects
185 The following example demonstrates how to connect different voices
186 using ties. Normally, ties only connect two notes in the same
187 voice. By introducing a tie in a different voice,
189 @lilypond[quote,fragment,relative=2]
198 and blanking the first up-stem in that voice, the tie appears to cross
201 @lilypond[quote,fragment,relative=2,verbatim]
203 \once \override Stem #'transparent = ##t
211 The @code{padding} property for objects with
212 @cindex @code{padding}
213 @code{side-position-interface} can be set to increase the distance between
214 symbols that are printed above or below notes. We provide two
215 examples; a more elaborate explanation is in @ref{Constructing a
218 @lilypond[quote,fragment,relative=1,verbatim]
220 \override Script #'padding = #3
224 @lilypond[quote,fragment,relative=1,verbatim]
225 % This will not work, see below:
226 \override MetronomeMark #'padding = #3
230 \override Score.MetronomeMark #'padding = #3
235 Note in the second example how important it is to figure out what
236 context handles a certain object. Since the @code{MetronomeMark} object
237 is handled in the Score context, property changes in the @code{Voice}
238 context will not be noticed.
242 Some tweakable options are called ``subproperties'' and reside inside
243 properties. To tweak those, use
246 \override Stem #'details #'beamed-lengths = #'(4 4 3)
249 @cindex Tweaks, distances
252 Distances in LilyPond are measured in staff-spaces, while most
253 thickness properties are measured in line-thickness. Some
254 properties are different; for example, the thickness of beams
255 is measured in staff-spaces. For more information, see the
256 relevant portion of the program reference.
258 More specific overrides are also possible. The next section
259 discusses in depth how to figure out these statements for yourself.
262 @node Advanced tweaks with scheme
263 @section Advanced tweaks with scheme
265 We have seen how LilyPond output can be heavily modified using
267 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
268 we have even more power if we use scheme.