1 @c -*- coding: utf-8; mode: texinfo; -*-
3 @chapter Tweaking output
5 This chapter discusses how modify output. LilyPond is extremely
6 configurable; virtually every fragment of output may be changed.
10 * Fixing overlapping notation::
13 * Advanced tweaks with scheme::
17 @node Fixing overlapping notation
18 @section Fixing overlapping notation
20 This may come as a surprise, but LilyPond isn't perfect. Some notation
21 elements can overlap. This is unfortunate, but (in most cases) is easily
24 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
25 e4^\markup{ \italic ritenuto } g b e
30 The easiest solution is to increase the distance between the object
31 (in this case text, but it could easily be fingerings or dynamics
32 instead) and the note. In LilyPond, this is called the
33 @code{padding} property; it is measured in staff spaces. For most
34 objects, this value is around 1.0 or less (it varies with each
35 object). We want to increase it, so let's try 1.5
37 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
38 \once \override TextScript #'padding = #1.5
39 e4^\markup{ \italic ritenuto } g b e
42 That looks better, but it isn't quite big enough. After experimenting
43 with a few values, we think 2.3 is the best number in this case. However,
44 this number is merely the result of experimentation and my personal
45 taste in notation. Try the above example with 2.3... but also try higher
46 (and lower) numbers. Which do you think looks the best?
48 The @code{staff-padding} property is closely related. @code{padding}
49 controls the minimum amount of space between an object and the nearest
50 other object (generally the note or the staff lines);
51 @code{staff-padding} controls the minimum amount of space between an
52 object and the staff. This is a subtle difference, but you can see
55 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
57 \once \override TextScript #'padding = #2.6
59 \once \override TextScript #'staff-padding = #2.6
60 c4^"piu mosso" fis a g
62 c,,4^"piu mosso" b a b
63 \once \override TextScript #'padding = #2.6
65 \once \override TextScript #'staff-padding = #2.6
66 c4^"piu mosso" fis a g
71 Another solution gives us complete control over placing the object -- we
72 can move it horizontally or vertically. This is done with the
73 @code{extra-offset} property. It is slightly more complicated and can
74 cause other problems. When we move objects with @code{extra-offset},
75 the movement is done after LilyPond has placed all other objects. This means
76 that the result can overlap with other objects.
78 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
79 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
80 e4^\markup{ \italic ritenuto } g b e
83 With @code{extra-offset}, the first number controls the horizontal
84 movement (left is negative); the second number controls the vertical
85 movement (up is positive). After a bit of experimenting, we decided
86 that these values look good
88 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
89 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
90 e4^\markup{ \italic ritenuto } g b e
94 Again, these numbers are simply the result of a few experiments and
95 looking at the output. You might prefer the text to be slightly higher,
96 or to the left, or whatever. Try it and look at the result!
98 One final warning: in this section, we used
101 \once \override TextScript @dots{}
104 This tweaks the display of text for the next note. If the note has
105 no text, this tweak does nothing (and does @strong{not} wait until
106 the next bit of text). To change the behavior of everything after
107 the command, omit the @code{\once}. To stop this tweak, use a
108 @code{\revert}. This is explained in depth in
109 @ref{The \override command}.
111 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
113 \once \override TextScript #'padding = #2.6
116 \once \override TextScript #'padding = #2.6
120 \override TextScript #'padding = #2.6
123 \revert TextScript #'padding
130 This manual: @ref{The \override command}, @ref{Common tweaks}.
134 @section Common tweaks
136 Some overrides are so common that predefined commands are provided as
137 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
138 commands are described in the Notation Reference under the appropriate
141 The complete list of modifications available for each type of
142 object (like slurs or beams) are documented in the Program
143 Reference. However, many layout objects share properties, which can be
144 used to apply generic tweaks.
148 @cindex @code{padding}
149 @item The @code{padding} property can be set to increase
150 (or decrease) the distance between symbols that are printed
151 above or below notes. This applies to all objects with
152 @code{side-position-interface}.
154 @lilypond[quote,fragment,relative=1,verbatim]
156 \override Script #'padding = #3
160 @lilypond[quote,fragment,relative=1,verbatim]
161 % This will not work, see below:
162 \override MetronomeMark #'padding = #3
166 \override Score.MetronomeMark #'padding = #3
171 Note in the second example how important it is to figure out what
172 context handles a certain object. Since the @code{MetronomeMark} object
173 is handled in the Score context, property changes in the @code{Voice}
174 context will not be noticed. For more details, see
175 @ref{Constructing a tweak}.
177 @cindex @code{extra-offset}
178 @item The @code{extra-offset} property moves objects around
179 in the output; it requires a pair of numbers. The first number
180 controls horizontal movement; a positive number will
181 move the object to the right. The second number controls vertical
182 movement; a positive number will move it higher. The
183 @code{extra-offset} property is a low-level feature: the
184 formatting engine is completely oblivious to these offsets.
186 In the following example, the second fingering is moved a little to
187 the left, and 1.8 staff space downwards:
189 @lilypond[quote,fragment,relative=1,verbatim]
192 \once \override Fingering
193 #'extra-offset = #'(-0.3 . -1.8)
198 Setting the @code{transparent} property will cause an object to be printed
199 in `invisible ink': the object is not printed, but all its other
200 behavior is retained. The object still takes up space, it takes part in
201 collisions, and slurs, ties, and beams can be attached to it.
203 @cindex transparent objects
204 @cindex removing objects
205 @cindex hiding objects
206 @cindex invisible objects
207 The following example demonstrates how to connect different voices
208 using ties. Normally, ties only connect two notes in the same
209 voice. By introducing a tie in a different voice,
211 @lilypond[quote,fragment,relative=2]
220 and blanking the first up-stem in that voice, the tie appears to cross
223 @lilypond[quote,fragment,relative=2,verbatim]
225 \once \override Stem #'transparent = ##t
234 @cindex Tweaks, distances
237 Distances in LilyPond are measured in staff-spaces, while most
238 thickness properties are measured in line-thickness. Some
239 properties are different; for example, the thickness of beams
240 is measured in staff-spaces. For more information, see the
241 relevant portion of the program reference.
245 @section Default files
247 The Program Reference documentation contains a lot of information
248 about LilyPond, but even more information can be gathered from
249 looking at the internal LilyPond files.
251 Some default settings (such as the definitions for
252 @code{\header@{@}}s) are stored as @code{.ly} files. Other
253 settings (such as the definitions of markup commands) are
254 stored as @code{.scm} (Scheme) files. Further explanation is
255 outside the scope of this manual; users should be warned that
256 a substantial amount of technical knowledge or time is required
257 to understand these files.
261 @item Linux: @file{/usr/ ... }
264 @file{@{LILYPOND_INSTALLED_DIR@}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
265 To access this, either @code{cd} into this directory from
266 the Terminal, or control-click on the LilyPond application
267 and select "Show Package Contents".
273 The @file{ly/} and @file{scm/} directories will be of
274 particular interest. Files such as @file{ly/property-init.ly} and
275 @file{ly/declarations-init.ly} define all the common tweaks.
278 @node Advanced tweaks with scheme
279 @section Advanced tweaks with scheme
281 We have seen how LilyPond output can be heavily modified using
283 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
284 we have even more power if we use scheme. For a full explantion
285 of this, see @ref{Interfaces for programmers}.
287 We can use scheme to simply @code{\override} commands,
289 @lilypond[quote,verbatim,ragged-right]
290 padText = #(define-music-function (parser location padding) (number?)
292 \once \override TextScript #'padding = #$padding
300 c4^"piu mosso" fis a g
304 We can use it to create new commands,
306 @lilypond[quote,verbatim,ragged-right]
307 tempoMark = #(define-music-function (parser location marktext padding) (string? number?)
309 \once \override Score . RehearsalMark #'padding = $padding
310 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
311 \mark \markup { \bold $marktext }
316 \tempoMark #"Allegro" #3.0
321 Even music expressions can be passed in. Note that since we
322 want an articulation attached to the second variable, we
325 @lilypond[quote,verbatim,ragged-right]
326 %pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
328 % $x e8-. a-. b-. $y-.-> b-. a-. e-.