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::
16 * Avoiding tweaks with slower processing::
21 @section Moving objects
23 This may come as a surprise, but LilyPond is not perfect. Some notation
24 elements can overlap. This is unfortunate, but (in most cases) is easily
27 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
28 e4^\markup{ \italic ritenuto } g b e
33 The easiest solution is to increase the distance between the object
34 (in this case text, but it could easily be fingerings or dynamics
35 instead) and the note. In LilyPond, this is called the
36 @code{padding} property; it is measured in staff spaces. For most
37 objects, this value is around 1.0 or less (it varies with each
38 object). We want to increase it, so let's try 1.5
40 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
41 \once \override TextScript #'padding = #1.5
42 e4^\markup{ \italic ritenuto } g b e
45 That looks better, but it isn't quite big enough. After experimenting
46 with a few values, we think 2.3 is the best number in this case. However,
47 this number is merely the result of experimentation and my personal
48 taste in notation. Try the above example with 2.3... but also try higher
49 (and lower) numbers. Which do you think looks the best?
51 The @code{staff-padding} property is closely related. @code{padding}
52 controls the minimum amount of space between an object and the nearest
53 other object (generally the note or the staff lines);
54 @code{staff-padding} controls the minimum amount of space between an
55 object and the staff. This is a subtle difference, but you can see
58 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
60 \once \override TextScript #'padding = #2.6
62 \once \override TextScript #'staff-padding = #2.6
63 c4^"piu mosso" fis a g
66 \once \override TextScript #'padding = #2.6
68 \once \override TextScript #'staff-padding = #2.6
69 c4^"piu mosso" fis a g
74 Another solution gives us complete control over placing the object -- we
75 can move it horizontally or vertically. This is done with the
76 @code{extra-offset} property. It is slightly more complicated and can
77 cause other problems. When we move objects with @code{extra-offset},
78 the movement is done after LilyPond has placed all other objects. This
80 that the result can overlap with other objects.
82 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
83 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
84 e4^\markup{ \italic ritenuto } g b e
87 With @code{extra-offset}, the first number controls the horizontal
88 movement (left is negative); the second number controls the vertical
89 movement (up is positive). After a bit of experimenting, we decided
90 that these values look good
92 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
93 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
94 e4^\markup{ \italic ritenuto } g b e
98 Again, these numbers are simply the result of a few experiments and
99 looking at the output. You might prefer the text to be slightly higher,
100 or to the left, or whatever. Try it and look at the result!
102 One final warning: in this section, we used
105 \once \override TextScript @dots{}
108 This tweaks the display of text for the next note. If the note has
109 no text, this tweak does nothing (and does @strong{not} wait until
110 the next bit of text). To change the behavior of everything after
111 the command, omit the @code{\once}. To stop this tweak, use a
112 @code{\revert}. This is explained in depth in
113 @ref{The \override command}.
115 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
117 \once \override TextScript #'padding = #2.6
120 \once \override TextScript #'padding = #2.6
124 \override TextScript #'padding = #2.6
127 \revert TextScript #'padding
133 This manual: @ref{The \override command}, @ref{Common tweaks}.
136 @node Fixing overlapping notation
137 @section Fixing overlapping notation
139 In @ref{Moving objects}, we saw how to move a @code{TextScript}
140 object. The same mechanism can be used to move other types of
141 objects; simply replace @code{TextScript} with the name of
144 To find the object name, look at the ``@strong{see also}'' at
145 bottom of the relevant documentation page. For example, at
146 the bottom of @ref{Dynamics}, we see
151 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
152 Vertical positioning of these symbols is handled by
153 @internalsref{DynamicLineSpanner}.
157 So to move dynamics around vertically, we use
160 \override DynamicLineSpanner #'padding = #2.0
163 We cannot list every object, but here is a list of the most
166 @multitable @columnfractions .33 .66
167 @headitem Object type @tab Object name
168 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
169 @item Dynamics (horizontally) @tab @code{DynamicText}
170 @item Ties @tab @code{Tie}
171 @item Slurs @tab @code{Slur}
172 @item Articulations @tab @code{Script}
173 @item Fingerings @tab @code{Fingering}
174 @item Text e.g. @code{^"text"} @tab @code{TextScript}
175 @item Rehearsal / Text marks @tab @code{RehearsalMark}
180 @section Common tweaks
182 Some overrides are so common that predefined commands are provided as
183 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
184 commands are described in the Notation Reference under the appropriate
187 The complete list of modifications available for each type of
188 object (like slurs or beams) are documented in the Program
189 Reference. However, many layout objects share properties which can be
190 used to apply generic tweaks.
197 The @code{padding} property can be set to increase
198 (or decrease) the distance between symbols that are printed
199 above or below notes. This applies to all objects with
200 @code{side-position-interface}.
202 @lilypond[quote,fragment,relative=1,verbatim]
204 \override Script #'padding = #3
208 @lilypond[quote,fragment,relative=1,verbatim]
209 % This will not work, see below:
210 \override MetronomeMark #'padding = #3
214 \override Score.MetronomeMark #'padding = #3
219 Note in the second example how important it is to figure out what
220 context handles a certain object. Since the @code{MetronomeMark} object
221 is handled in the @code{Score} context, property changes in the
222 @code{Voice} context will not be noticed. For more details, see
223 @ref{Constructing a tweak}.
228 The @code{extra-offset} property moves objects around
229 in the output; it requires a pair of numbers. The first number
230 controls horizontal movement; a positive number will
231 move the object to the right. The second number controls vertical
232 movement; a positive number will move it higher. The
233 @code{extra-offset} property is a low-level feature: the
234 formatting engine is completely oblivious to these offsets.
236 In the following example, the second fingering is moved a little to
237 the left, and 1.8 staff space downwards:
239 @lilypond[quote,fragment,relative=1,verbatim]
242 \once \override Fingering
243 #'extra-offset = #'(-0.3 . -1.8)
248 Setting the @code{transparent} property will cause an object to be printed
249 in `invisible ink': the object is not printed, but all its other
250 behavior is retained. The object still takes up space, it takes part in
251 collisions, and slurs, ties, and beams can be attached to it.
253 @cindex transparent objects
254 @cindex removing objects
255 @cindex hiding objects
256 @cindex invisible objects
257 The following example demonstrates how to connect different voices
258 using ties. Normally, ties only connect two notes in the same
259 voice. By introducing a tie in a different voice,
261 @lilypond[quote,fragment,relative=2]
270 and blanking the first up-stem in that voice, the tie appears to cross
274 @lilypond[quote,fragment,relative=2,verbatim]
276 \once \override Stem #'transparent = ##t
283 To make sure that the just blanked stem doesn't sqeeuze the too much
284 tie, we also lengthen the stem, by setting the @code{length} to
287 @lilypond[quote,fragment,relative=2,verbatim]
289 \once \override Stem #'transparent = ##t
290 \once \override Stem #'length = #8
299 @cindex Tweaks, distances
302 Distances in LilyPond are measured in staff-spaces, while most
303 thickness properties are measured in line-thickness. Some
304 properties are different; for example, the thickness of beams
305 are measured in staff-spaces. For more information, see the
306 relevant portion of the program reference.
310 @section Default files
312 The Program Reference documentation contains a lot of information
313 about LilyPond, but even more information can be gathered from
314 looking at the internal LilyPond files.
316 Some default settings (such as the definitions for
317 @code{\header@{@}}s) are stored as @code{.ly} files. Other
318 settings (such as the definitions of markup commands) are
319 stored as @code{.scm} (Scheme) files. Further explanation is
320 outside the scope of this manual; users should be warned that
321 a substantial amount of technical knowledge or time is required
322 to understand these files.
326 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
329 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
330 To access this, either @code{cd} into this directory from the
331 Terminal, or control-click on the LilyPond application and select
332 "Show Package Contents".
334 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
338 The @file{ly/} and @file{scm/} directories will be of
339 particular interest. Files such as @file{ly/property-init.ly} and
340 @file{ly/declarations-init.ly} define all the common tweaks.
343 @node Fitting music onto fewer pages
344 @section Fitting music onto fewer pages
346 Sometimes you can end up with one or two staves on a second
347 (or third, or fourth...) page. This is annoying, especially
348 if you look at previous pages and it looks like there is plenty
349 of room left on those.
351 When investigating layout issues, @code{annotate-spacing} is
352 an invaluable tool. This command prints the values of various
353 layout spacing commands; see @ref{Displaying spacing} for more
354 details. From the output of @code{annotate-spacing}, we can
355 see which margins we may wish to alter.
357 Other than margins, there are a few other options to save space:
361 You may tell LilyPond to place systems as close together as
362 possible (to fit as many systems as possible onto a page), but
363 then to space those systems out so that there is no blank
364 space at the bottom of the page.
368 between-system-padding = #0.1
369 between-system-space = #0.1
370 ragged-last-bottom = ##f
376 You may force the number of systems (i.e., if LilyPond wants
377 to typeset some music with 11 systems, you could force it to
387 Avoid (or reduce) objects which increase the vertical size of
388 a system. For example, volta repeats (or alternate repeats)
389 require extra space. If these repeats are spread over two
390 systems, they will take up more space than one system with
391 the volta repeats and another system without.
393 Another example is moving dynamics which ``stick out'' of
396 @lilypond[verbatim,quote,fragment]
399 \override DynamicLineSpanner #'padding = #-1.8
400 \override DynamicText #'extra-offset = #'( -2.1 . 0)
406 Alter the horizontal spacing via @code{SpacingSpanner}. See
407 @ref{Changing horizontal spacing} for more details.
409 @lilypond[verbatim,quote]
412 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
413 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
414 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
415 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
420 \override SpacingSpanner
421 #'base-shortest-duration = #(ly:make-moment 1 4)
430 @node Advanced tweaks with Scheme
431 @section Advanced tweaks with Scheme
433 We have seen how LilyPond output can be heavily modified using
435 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
436 we have even more power if we use Scheme. For a full explantion
437 of this, see the @ref{Scheme tutorial} and
438 @ref{Interfaces for programmers}.
440 We can use Scheme to simply @code{\override} commands,
442 @lilypond[quote,verbatim,ragged-right]
443 padText = #(define-music-function (parser location padding) (number?)
445 \once \override TextScript #'padding = #$padding
453 c4^"piu mosso" fis a g
457 We can use it to create new commands,
459 @lilypond[quote,verbatim,ragged-right]
460 tempoMark = #(define-music-function (parser location padding marktext)
463 \once \override Score . RehearsalMark #'padding = $padding
464 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
465 \mark \markup { \bold $marktext }
470 \tempoMark #3.0 #"Allegro"
475 Even music expressions can be passed in.
477 @lilypond[quote,verbatim,ragged-right]
478 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
485 \pattern {d16 dis} { ais16-> b\p }
490 @node Avoiding tweaks with slower processing
491 @section Avoiding tweaks with slower processing
493 LilyPond can perform extra checks while it processes files. These
494 commands will take extra time, but the result may require fewer
498 %% makes sure text scripts and lyrics are within the paper margins
499 \override Score.PaperColumn #'keep-inside-line = ##t