1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
11 @chapter Tweaking output
13 This chapter discusses how to modify output. LilyPond is extremely
14 configurable; virtually every fragment of output may be changed.
19 * Fixing overlapping notation::
22 * Fitting music onto fewer pages::
23 * Advanced tweaks with Scheme::
24 * Avoiding tweaks with slower processing::
29 @section Moving objects
31 This may come as a surprise, but LilyPond is not perfect. Some notation
32 elements can overlap. This is unfortunate, but (in most cases) is easily
35 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
36 e4^\markup{ \italic ritenuto } g b e
41 The easiest solution is to increase the distance between the object
42 (in this case text, but it could easily be fingerings or dynamics
43 instead) and the note. In LilyPond, this is called the
44 @code{padding} property; it is measured in staff spaces. For most
45 objects, this value is around 1.0 or less (it varies with each
46 object). We want to increase it, so let's try 1.5
48 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
49 \once \override TextScript #'padding = #1.5
50 e4^\markup{ \italic ritenuto } g b e
53 That looks better, but it isn't quite big enough. After experimenting
54 with a few values, we think 2.3 is the best number in this case. However,
55 this number is merely the result of experimentation and my personal
56 taste in notation. Try the above example with 2.3... but also try higher
57 (and lower) numbers. Which do you think looks the best?
59 The @code{staff-padding} property is closely related. @code{padding}
60 controls the minimum amount of space between an object and the nearest
61 other object (generally the note or the staff lines);
62 @code{staff-padding} controls the minimum amount of space between an
63 object and the staff. This is a subtle difference, but you can see
66 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
68 \once \override TextScript #'padding = #2.6
70 \once \override TextScript #'staff-padding = #2.6
71 c4^"piu mosso" fis a g
74 \once \override TextScript #'padding = #2.6
76 \once \override TextScript #'staff-padding = #2.6
77 c4^"piu mosso" fis a g
82 Another solution gives us complete control over placing the object -- we
83 can move it horizontally or vertically. This is done with the
84 @code{extra-offset} property. It is slightly more complicated and can
85 cause other problems. When we move objects with @code{extra-offset},
86 the movement is done after LilyPond has placed all other objects. This
88 that the result can overlap with other objects.
90 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
91 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
92 e4^\markup{ \italic ritenuto } g b e
95 With @code{extra-offset}, the first number controls the horizontal
96 movement (left is negative); the second number controls the vertical
97 movement (up is positive). After a bit of experimenting, we decided
98 that these values look good
100 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
101 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
102 e4^\markup{ \italic ritenuto } g b e
106 Again, these numbers are simply the result of a few experiments and
107 looking at the output. You might prefer the text to be slightly higher,
108 or to the left, or whatever. Try it and look at the result!
110 One final warning: in this section, we used
113 \once \override TextScript @dots{}
116 This tweaks the display of text for the next note. If the note has
117 no text, this tweak does nothing (and does @strong{not} wait until
118 the next bit of text). To change the behavior of everything after
119 the command, omit the @code{\once}. To stop this tweak, use a
120 @code{\revert}. This is explained in depth in
121 @ref{The \override command}.
123 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
125 \once \override TextScript #'padding = #2.6
128 \once \override TextScript #'padding = #2.6
132 \override TextScript #'padding = #2.6
135 \revert TextScript #'padding
141 This manual: @ref{The \override command}, @ref{Common tweaks}.
144 @node Fixing overlapping notation
145 @section Fixing overlapping notation
147 In @ref{Moving objects}, we saw how to move a @code{TextScript}
148 object. The same mechanism can be used to move other types of
149 objects; simply replace @code{TextScript} with the name of
152 To find the object name, look at the ``@strong{see also}'' at
153 bottom of the relevant documentation page. For example, at
154 the bottom of @ref{Dynamics}, we see
159 Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
160 Vertical positioning of these symbols is handled by
161 @internalsref{DynamicLineSpanner}.
165 So to move dynamics around vertically, we use
168 \override DynamicLineSpanner #'padding = #2.0
171 We cannot list every object, but here is a list of the most
174 @multitable @columnfractions .33 .66
175 @headitem Object type @tab Object name
176 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
177 @item Dynamics (horizontally) @tab @code{DynamicText}
178 @item Ties @tab @code{Tie}
179 @item Slurs @tab @code{Slur}
180 @item Articulations @tab @code{Script}
181 @item Fingerings @tab @code{Fingering}
182 @item Text e.g. @code{^"text"} @tab @code{TextScript}
183 @item Rehearsal / Text marks @tab @code{RehearsalMark}
188 @section Common tweaks
190 Some overrides are so common that predefined commands are provided as
191 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
192 commands are described in the Notation Reference under the appropriate
195 The complete list of modifications available for each type of
196 object (like slurs or beams) are documented in the Program
197 Reference. However, many layout objects share properties which can be
198 used to apply generic tweaks.
205 The @code{padding} property can be set to increase
206 (or decrease) the distance between symbols that are printed
207 above or below notes. This applies to all objects with
208 @code{side-position-interface}.
210 @lilypond[quote,fragment,relative=1,verbatim]
212 \override Script #'padding = #3
216 @lilypond[quote,fragment,relative=1,verbatim]
217 % This will not work, see below:
218 \override MetronomeMark #'padding = #3
222 \override Score.MetronomeMark #'padding = #3
227 Note in the second example how important it is to figure out what
228 context handles a certain object. Since the @code{MetronomeMark} object
229 is handled in the @code{Score} context, property changes in the
230 @code{Voice} context will not be noticed. For more details, see
231 @ref{Constructing a tweak}.
236 The @code{extra-offset} property moves objects around
237 in the output; it requires a pair of numbers. The first number
238 controls horizontal movement; a positive number will
239 move the object to the right. The second number controls vertical
240 movement; a positive number will move it higher. The
241 @code{extra-offset} property is a low-level feature: the
242 formatting engine is completely oblivious to these offsets.
244 In the following example, the second fingering is moved a little to
245 the left, and 1.8 staff space downwards:
247 @lilypond[quote,fragment,relative=1,verbatim]
250 \once \override Fingering
251 #'extra-offset = #'(-0.3 . -1.8)
256 Setting the @code{transparent} property will cause an object to be printed
257 in `invisible ink': the object is not printed, but all its other
258 behavior is retained. The object still takes up space, it takes part in
259 collisions, and slurs, ties, and beams can be attached to it.
261 @cindex transparent objects
262 @cindex removing objects
263 @cindex hiding objects
264 @cindex invisible objects
265 The following example demonstrates how to connect different voices
266 using ties. Normally, ties only connect two notes in the same
267 voice. By introducing a tie in a different voice,
269 @lilypond[quote,fragment,relative=2]
278 and blanking the first up-stem in that voice, the tie appears to cross
282 @lilypond[quote,fragment,relative=2,verbatim]
284 \once \override Stem #'transparent = ##t
291 To make sure that the just blanked stem doesn't sqeeuze the too much
292 tie, we also lengthen the stem, by setting the @code{length} to
295 @lilypond[quote,fragment,relative=2,verbatim]
297 \once \override Stem #'transparent = ##t
298 \once \override Stem #'length = #8
307 @cindex Tweaks, distances
310 Distances in LilyPond are measured in staff-spaces, while most
311 thickness properties are measured in line-thickness. Some
312 properties are different; for example, the thickness of beams
313 are measured in staff-spaces. For more information, see the
314 relevant portion of the program reference.
318 @section Default files
320 The Program Reference documentation contains a lot of information
321 about LilyPond, but even more information can be gathered from
322 looking at the internal LilyPond files.
324 Some default settings (such as the definitions for
325 @code{\header@{@}}s) are stored as @code{.ly} files. Other
326 settings (such as the definitions of markup commands) are
327 stored as @code{.scm} (Scheme) files. Further explanation is
328 outside the scope of this manual; users should be warned that
329 a substantial amount of technical knowledge or time is required
330 to understand these files.
334 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
337 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
338 To access this, either @code{cd} into this directory from the
339 Terminal, or control-click on the LilyPond application and select
340 "Show Package Contents".
342 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
346 The @file{ly/} and @file{scm/} directories will be of
347 particular interest. Files such as @file{ly/property-init.ly} and
348 @file{ly/declarations-init.ly} define all the common tweaks.
351 @node Fitting music onto fewer pages
352 @section Fitting music onto fewer pages
354 Sometimes you can end up with one or two staves on a second
355 (or third, or fourth...) page. This is annoying, especially
356 if you look at previous pages and it looks like there is plenty
357 of room left on those.
359 When investigating layout issues, @code{annotate-spacing} is
360 an invaluable tool. This command prints the values of various
361 layout spacing commands; see @ref{Displaying spacing} for more
362 details. From the output of @code{annotate-spacing}, we can
363 see which margins we may wish to alter.
365 Other than margins, there are a few other options to save space:
369 You may tell LilyPond to place systems as close together as
370 possible (to fit as many systems as possible onto a page), but
371 then to space those systems out so that there is no blank
372 space at the bottom of the page.
376 between-system-padding = #0.1
377 between-system-space = #0.1
378 ragged-last-bottom = ##f
384 You may force the number of systems (i.e., if LilyPond wants
385 to typeset some music with 11 systems, you could force it to
395 Avoid (or reduce) objects which increase the vertical size of
396 a system. For example, volta repeats (or alternate repeats)
397 require extra space. If these repeats are spread over two
398 systems, they will take up more space than one system with
399 the volta repeats and another system without.
401 Another example is moving dynamics which ``stick out'' of
404 @lilypond[verbatim,quote,fragment]
407 \override DynamicLineSpanner #'padding = #-1.8
408 \override DynamicText #'extra-offset = #'( -2.1 . 0)
414 Alter the horizontal spacing via @code{SpacingSpanner}. See
415 @ref{Changing horizontal spacing} for more details.
417 @lilypond[verbatim,quote]
420 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
421 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
422 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
423 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
428 \override SpacingSpanner
429 #'base-shortest-duration = #(ly:make-moment 1 4)
438 @node Advanced tweaks with Scheme
439 @section Advanced tweaks with Scheme
441 We have seen how LilyPond output can be heavily modified using
443 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
444 we have even more power if we use Scheme. For a full explantion
445 of this, see the @ref{Scheme tutorial} and
446 @ref{Interfaces for programmers}.
448 We can use Scheme to simply @code{\override} commands,
450 @lilypond[quote,verbatim,ragged-right]
451 padText = #(define-music-function (parser location padding) (number?)
453 \once \override TextScript #'padding = #$padding
461 c4^"piu mosso" fis a g
465 We can use it to create new commands,
467 @lilypond[quote,verbatim,ragged-right]
468 tempoMark = #(define-music-function (parser location padding marktext)
471 \once \override Score . RehearsalMark #'padding = $padding
472 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
473 \mark \markup { \bold $marktext }
478 \tempoMark #3.0 #"Allegro"
483 Even music expressions can be passed in.
485 @lilypond[quote,verbatim,ragged-right]
486 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
493 \pattern {d16 dis} { ais16-> b\p }
498 @node Avoiding tweaks with slower processing
499 @section Avoiding tweaks with slower processing
501 LilyPond can perform extra checks while it processes files. These
502 commands will take extra time, but the result may require fewer
506 %% makes sure text scripts and lyrics are within the paper margins
507 \override Score.PaperColumn #'keep-inside-line = ##t