1 @c -*- coding: utf-8; mode: texinfo; -*-
3 @chapter Tweaking output
5 This chapter discusses how to modify output. LilyPond is extremely
6 configurable; virtually every fragment of output may be changed.
11 * Fixing overlapping notation::
14 * Fitting music onto fewer pages::
15 * Advanced tweaks with Scheme::
20 @section Moving objects
22 This may come as a surprise, but LilyPond is not perfect. Some notation
23 elements can overlap. This is unfortunate, but (in most cases) is easily
26 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
27 e4^\markup{ \italic ritenuto } g b e
32 The easiest solution is to increase the distance between the object
33 (in this case text, but it could easily be fingerings or dynamics
34 instead) and the note. In LilyPond, this is called the
35 @code{padding} property; it is measured in staff spaces. For most
36 objects, this value is around 1.0 or less (it varies with each
37 object). We want to increase it, so let's try 1.5
39 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
40 \once \override TextScript #'padding = #1.5
41 e4^\markup{ \italic ritenuto } g b e
44 That looks better, but it isn't quite big enough. After experimenting
45 with a few values, we think 2.3 is the best number in this case. However,
46 this number is merely the result of experimentation and my personal
47 taste in notation. Try the above example with 2.3... but also try higher
48 (and lower) numbers. Which do you think looks the best?
50 The @code{staff-padding} property is closely related. @code{padding}
51 controls the minimum amount of space between an object and the nearest
52 other object (generally the note or the staff lines);
53 @code{staff-padding} controls the minimum amount of space between an
54 object and the staff. This is a subtle difference, but you can see
57 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
59 \once \override TextScript #'padding = #2.6
61 \once \override TextScript #'staff-padding = #2.6
62 c4^"piu mosso" fis a g
65 \once \override TextScript #'padding = #2.6
67 \once \override TextScript #'staff-padding = #2.6
68 c4^"piu mosso" fis a g
73 Another solution gives us complete control over placing the object -- we
74 can move it horizontally or vertically. This is done with the
75 @code{extra-offset} property. It is slightly more complicated and can
76 cause other problems. When we move objects with @code{extra-offset},
77 the movement is done after LilyPond has placed all other objects. This
79 that the result can overlap with other objects.
81 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
82 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
83 e4^\markup{ \italic ritenuto } g b e
86 With @code{extra-offset}, the first number controls the horizontal
87 movement (left is negative); the second number controls the vertical
88 movement (up is positive). After a bit of experimenting, we decided
89 that these values look good
91 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
92 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
93 e4^\markup{ \italic ritenuto } g b e
97 Again, these numbers are simply the result of a few experiments and
98 looking at the output. You might prefer the text to be slightly higher,
99 or to the left, or whatever. Try it and look at the result!
101 One final warning: in this section, we used
104 \once \override TextScript @dots{}
107 This tweaks the display of text for the next note. If the note has
108 no text, this tweak does nothing (and does @strong{not} wait until
109 the next bit of text). To change the behavior of everything after
110 the command, omit the @code{\once}. To stop this tweak, use a
111 @code{\revert}. This is explained in depth in
112 @ref{The \override command}.
114 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
116 \once \override TextScript #'padding = #2.6
119 \once \override TextScript #'padding = #2.6
123 \override TextScript #'padding = #2.6
126 \revert TextScript #'padding
132 This manual: @ref{The \override command}, @ref{Common tweaks}.
135 @node Fixing overlapping notation
136 @section Fixing overlapping notation
138 In @ref{Moving objects}, we saw how to move a @code{TextScript}
139 object. The same mechanism can be used to move other types of
140 objects; simply replace @code{TextScript} with the name of
143 To find the object name, look at the ``@strong{see also}'' at
144 bottom of the relevant documentation page. For example, at
145 the bottom of @ref{Dynamics}, we see
150 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
151 Vertical positioning of these symbols is handled by
152 @internalsref{DynamicLineSpanner}.
156 So to move dynamics around vertically, we use
159 \override DynamicLineSpanner #'padding = #2.0
162 We cannot list every object, but here is a list of the most
165 @multitable @columnfractions .33 .66
166 @headitem Object type @tab Object name
167 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
168 @item Dynamics (horizontally) @tab @code{DynamicText}
169 @item Ties @tab @code{Tie}
170 @item Slurs @tab @code{Slur}
171 @item Articulations @tab @code{Script}
172 @item Fingerings @tab @code{Fingering}
173 @item Text e.g. @code{^"text"} @tab @code{TextScript}
174 @item Rehearsal / Text marks @tab @code{RehearsalMark}
179 @section Common tweaks
181 Some overrides are so common that predefined commands are provided as
182 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
183 commands are described in the Notation Reference under the appropriate
186 The complete list of modifications available for each type of
187 object (like slurs or beams) are documented in the Program
188 Reference. However, many layout objects share properties which can be
189 used to apply generic tweaks.
196 The @code{padding} property can be set to increase
197 (or decrease) the distance between symbols that are printed
198 above or below notes. This applies to all objects with
199 @code{side-position-interface}.
201 @lilypond[quote,fragment,relative=1,verbatim]
203 \override Script #'padding = #3
207 @lilypond[quote,fragment,relative=1,verbatim]
208 % This will not work, see below:
209 \override MetronomeMark #'padding = #3
213 \override Score.MetronomeMark #'padding = #3
218 Note in the second example how important it is to figure out what
219 context handles a certain object. Since the @code{MetronomeMark} object
220 is handled in the @code{Score} context, property changes in the
221 @code{Voice} context will not be noticed. For more details, see
222 @ref{Constructing a tweak}.
227 The @code{extra-offset} property moves objects around
228 in the output; it requires a pair of numbers. The first number
229 controls horizontal movement; a positive number will
230 move the object to the right. The second number controls vertical
231 movement; a positive number will move it higher. The
232 @code{extra-offset} property is a low-level feature: the
233 formatting engine is completely oblivious to these offsets.
235 In the following example, the second fingering is moved a little to
236 the left, and 1.8 staff space downwards:
238 @lilypond[quote,fragment,relative=1,verbatim]
241 \once \override Fingering
242 #'extra-offset = #'(-0.3 . -1.8)
247 Setting the @code{transparent} property will cause an object to be printed
248 in `invisible ink': the object is not printed, but all its other
249 behavior is retained. The object still takes up space, it takes part in
250 collisions, and slurs, ties, and beams can be attached to it.
252 @cindex transparent objects
253 @cindex removing objects
254 @cindex hiding objects
255 @cindex invisible objects
256 The following example demonstrates how to connect different voices
257 using ties. Normally, ties only connect two notes in the same
258 voice. By introducing a tie in a different voice,
260 @lilypond[quote,fragment,relative=2]
269 and blanking the first up-stem in that voice, the tie appears to cross
273 @lilypond[quote,fragment,relative=2,verbatim]
275 \once \override Stem #'transparent = ##t
282 To make sure that the just blanked stem doesn't sqeeuze the too much
283 tie, we also lengthen the stem, by setting the @code{length} to
286 @lilypond[quote,fragment,relative=2,verbatim]
288 \once \override Stem #'transparent = ##t
289 \once \override Stem #'length = #8
298 @cindex Tweaks, distances
301 Distances in LilyPond are measured in staff-spaces, while most
302 thickness properties are measured in line-thickness. Some
303 properties are different; for example, the thickness of beams
304 are measured in staff-spaces. For more information, see the
305 relevant portion of the program reference.
309 @section Default files
311 The Program Reference documentation contains a lot of information
312 about LilyPond, but even more information can be gathered from
313 looking at the internal LilyPond files.
315 Some default settings (such as the definitions for
316 @code{\header@{@}}s) are stored as @code{.ly} files. Other
317 settings (such as the definitions of markup commands) are
318 stored as @code{.scm} (Scheme) files. Further explanation is
319 outside the scope of this manual; users should be warned that
320 a substantial amount of technical knowledge or time is required
321 to understand these files.
325 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
328 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
329 To access this, either @code{cd} into this directory from the
330 Terminal, or control-click on the LilyPond application and select
331 "Show Package Contents".
333 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
337 The @file{ly/} and @file{scm/} directories will be of
338 particular interest. Files such as @file{ly/property-init.ly} and
339 @file{ly/declarations-init.ly} define all the common tweaks.
342 @node Fitting music onto fewer pages
343 @section Fitting music onto fewer pages
345 Sometimes you can end up with one or two staves on a second
346 (or third, or fourth...) page. This is annoying, especially
347 if you look at previous pages and it looks like there is plenty
348 of room left on those.
350 When investigating layout issues, @code{annotate-spacing} is
351 an invaluable tool. This command prints the values of various
352 layout spacing commands; see @ref{Displaying spacing} for more
353 details. From the output of @code{annotate-spacing}, we can
354 see which margins we may wish to alter.
356 Other than margins, there are a few other options to save space:
360 You may tell LilyPond to place systems as close together as
361 possible (to fit as many systems as possible onto a page), but
362 then to space those systems out so that there is no blank
363 space at the bottom of the page.
367 between-system-padding = #0.1
368 between-system-space = #0.1
369 ragged-last-bottom = ##f
375 You may force the number of systems (i.e., if LilyPond wants
376 to typeset some music with 11 systems, you could force it to
386 Avoid (or reduce) objects which increase the vertical size of
387 a system. For example, volta repeats (or alternate repeats)
388 require extra space. If these repeats are spread over two
389 systems, they will take up more space than one system with
390 the volta repeats and another system without.
392 Another example is moving dynamics which ``stick out'' of
395 @lilypond[verbatim,quote,fragment]
398 \override DynamicLineSpanner #'padding = #-1.8
399 \override DynamicText #'extra-offset = #'( -2.1 . 0)
405 Alter the horizontal spacing via @code{SpacingSpanner}. See
406 @ref{Changing horizontal spacing} for more details.
408 @lilypond[verbatim,quote]
411 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
412 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
413 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
414 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
419 \override SpacingSpanner
420 #'base-shortest-duration = #(ly:make-moment 1 4)
429 @node Advanced tweaks with Scheme
430 @section Advanced tweaks with Scheme
432 We have seen how LilyPond output can be heavily modified using
434 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
435 we have even more power if we use Scheme. For a full explantion
436 of this, see the @ref{Scheme tutorial} and
437 @ref{Interfaces for programmers}.
439 We can use Scheme to simply @code{\override} commands,
441 @lilypond[quote,verbatim,ragged-right]
442 padText = #(define-music-function (parser location padding) (number?)
444 \once \override TextScript #'padding = #$padding
452 c4^"piu mosso" fis a g
456 We can use it to create new commands,
458 @lilypond[quote,verbatim,ragged-right]
459 tempoMark = #(define-music-function (parser location padding marktext)
462 \once \override Score . RehearsalMark #'padding = $padding
463 \once \override Score . RehearsalMark #'no-spacing-rods = ##t
464 \mark \markup { \bold $marktext }
469 \tempoMark #3.0 #"Allegro"
474 Even music expressions can be passed in.
476 @lilypond[quote,verbatim,ragged-right]
477 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
484 \pattern {d16 dis} { ais16-> b\p }