]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/tweaks.itely
Proofreading from Dave Luttinen.
[lilypond.git] / Documentation / user / tweaks.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @node Tweaking output
3 @chapter Tweaking output
4
5 This chapter discusses how to modify output.  LilyPond is extremely
6 configurable; virtually every fragment of output may be changed.
7
8
9 @menu
10 * Fixing overlapping notation::  
11 * Common tweaks::               
12 * Default files::               
13 * Advanced tweaks with scheme::  
14 @end menu
15
16
17 @node Fixing overlapping notation
18 @section Fixing overlapping notation
19
20 This may come as a surprise, but LilyPond is not perfect.  Some notation
21 elements can overlap.  This is unfortunate, but (in most cases) is easily
22 solved.
23
24 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
25 e4^\markup{ \italic ritenuto } g b e
26 @end lilypond
27
28 @cindex padding
29
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
36
37 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
38 \once \override TextScript #'padding = #1.5
39 e4^\markup{ \italic ritenuto } g b e
40 @end lilypond
41
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?
47
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
53 the behavior here.
54
55 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
56 c4^"piu mosso" b a b
57 \once \override TextScript #'padding = #2.6
58 c4^"piu mosso" d e f
59 \once \override TextScript #'staff-padding = #2.6
60 c4^"piu mosso" fis a g
61 \break
62 c,,4^"piu mosso" b a b
63 \once \override TextScript #'padding = #2.6
64 c4^"piu mosso" d e f
65 \once \override TextScript #'staff-padding = #2.6
66 c4^"piu mosso" fis a g
67 @end lilypond
68
69 @cindex extra-offset
70
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 
76 means
77 that the result can overlap with other objects.
78
79 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
80 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
81 e4^\markup{ \italic ritenuto } g b e
82 @end lilypond
83
84 With @code{extra-offset}, the first number controls the horizontal
85 movement (left is negative); the second number controls the vertical
86 movement (up is positive).  After a bit of experimenting, we decided
87 that these values look good
88
89 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
90 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
91 e4^\markup{ \italic ritenuto } g b e
92 @end lilypond
93
94 @noindent
95 Again, these numbers are simply the result of a few experiments and
96 looking at the output.  You might prefer the text to be slightly higher,
97 or to the left, or whatever.  Try it and look at the result!
98
99 One final warning: in this section, we used
100
101 @example
102 \once \override TextScript @dots{}
103 @end example
104
105 This tweaks the display of text for the next note.  If the note has
106 no text, this tweak does nothing (and does @strong{not} wait until
107 the next bit of text).  To change the behavior of everything after
108 the command, omit the @code{\once}.  To stop this tweak, use a
109 @code{\revert}.  This is explained in depth in
110 @ref{The \override command}.
111
112 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
113 c4^"piu mosso" b
114 \once \override TextScript #'padding = #2.6
115   a4 b
116 c4^"piu mosso" d e f
117 \once \override TextScript #'padding = #2.6
118 c4^"piu mosso" d e f
119 c4^"piu mosso" d e f
120 \break
121 \override TextScript #'padding = #2.6
122 c4^"piu mosso" d e f
123 c4^"piu mosso" d e f
124 \revert TextScript #'padding
125 c4^"piu mosso" d e f
126 @end lilypond
127
128
129 @seealso
130
131 This manual: @ref{The \override command}, @ref{Common tweaks}.
132
133
134 @node Common tweaks
135 @section Common tweaks
136
137 Some overrides are so common that predefined commands are provided as
138 short-cuts, such as @code{\slurUp} and @code{\stemDown}.  These
139 commands are described in the Notation Reference under the appropriate
140 sections.
141
142 The complete list of modifications available for each type of
143 object (like slurs or beams) are documented in the Program
144 Reference.  However, many layout objects share properties which can be
145 used to apply generic tweaks.
146
147 @itemize @bullet
148
149 @cindex @code{padding}
150 @item The @code{padding} property can be set to increase
151 (or decrease) the distance between symbols that are printed
152 above or below notes.  This applies to all objects with
153 @code{side-position-interface}.
154
155 @lilypond[quote,fragment,relative=1,verbatim]
156 c2\fermata
157 \override Script #'padding = #3
158 b2\fermata
159 @end lilypond
160
161 @lilypond[quote,fragment,relative=1,verbatim]
162 % This will not work, see below:
163 \override MetronomeMark #'padding = #3
164 \tempo 4=120
165 c1
166 % This works:
167 \override Score.MetronomeMark #'padding = #3
168 \tempo 4=80
169 d1
170 @end lilypond
171
172 Note in the second example how important it is to figure out what
173 context handles a certain object.  Since the @code{MetronomeMark} object
174 is handled in the @code{Score} context, property changes in the
175 @code{Voice} context will not be noticed.  For more details, see
176 @ref{Constructing a tweak}.
177
178 @cindex @code{extra-offset}
179 @item The @code{extra-offset} property moves objects around
180 in the output; it requires a pair of numbers.  The first number
181 controls horizontal movement; a positive number will
182 move the object to the right.  The second number controls vertical
183 movement; a positive number will move it higher.  The
184 @code{extra-offset} property is a low-level feature: the
185 formatting engine is completely oblivious to these offsets.
186
187 In the following example, the second fingering is moved a little to
188 the left, and 1.8 staff space downwards:
189
190 @lilypond[quote,fragment,relative=1,verbatim]
191 \stemUp
192 f-5
193 \once \override Fingering
194     #'extra-offset = #'(-0.3 . -1.8)
195 f-5
196 @end lilypond
197
198 @item
199 Setting the @code{transparent} property will cause an object to be printed
200 in `invisible ink': the object is not printed, but all its other
201 behavior is retained.  The object still takes up space, it takes part in
202 collisions, and slurs, ties, and beams can be attached to it.
203
204 @cindex transparent objects
205 @cindex removing objects
206 @cindex hiding objects
207 @cindex invisible objects
208 The following example demonstrates how to connect different voices
209 using ties.  Normally, ties only connect two notes in the same
210 voice.  By introducing a tie in a different voice,
211
212 @lilypond[quote,fragment,relative=2]
213 << {
214   b8~ b8\noBeam
215 } \\ {
216   b[ g8]
217 } >>
218 @end lilypond
219
220 @noindent
221 and blanking the first up-stem in that voice, the tie appears to cross
222 voices:
223
224 @lilypond[quote,fragment,relative=2,verbatim]
225 << {
226   \once \override Stem #'transparent = ##t
227   b8~ b8\noBeam
228 } \\ {
229   b[ g8]
230 } >>
231 @end lilypond
232
233 @end itemize
234
235 @cindex Tweaks, distances
236 @cindex Distances
237
238 Distances in LilyPond are measured in staff-spaces, while most
239 thickness properties are measured in line-thickness.  Some
240 properties are different; for example, the thickness of beams
241 are measured in staff-spaces.  For more information, see the
242 relevant portion of the program reference.
243
244
245 @node Default files
246 @section Default files
247
248 The Program Reference documentation contains a lot of information
249 about LilyPond, but even more information can be gathered from
250 looking at the internal LilyPond files.
251
252 Some default settings (such as the definitions for
253 @code{\header@{@}}s) are stored as @code{.ly} files.  Other
254 settings (such as the definitions of markup commands) are
255 stored as @code{.scm} (Scheme) files.  Further explanation is
256 outside the scope of this manual; users should be warned that
257 a substantial amount of technical knowledge or time is required
258 to understand these files.
259
260 @itemize bullet
261
262 @item Linux: @file{@{INSTALLDIR@}/lilypond/usr/share/lilypond/current/}
263
264 @item OSX:
265 @file{@{INSTALLDIR@}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
266 To access this, either @code{cd} into this directory from
267 the Terminal, or control-click on the LilyPond application
268 and select "Show Package Contents".
269
270 @item Windows: @file{@{INSTALLDIR@}/LilyPond/usr/share/lilypond/current/}
271
272 @end itemize
273
274 The @file{ly/} and @file{scm/} directories will be of
275 particular interest.  Files such as @file{ly/property-init.ly} and
276 @file{ly/declarations-init.ly} define all the common tweaks.
277
278
279 @node Advanced tweaks with scheme
280 @section Advanced tweaks with scheme
281
282 We have seen how LilyPond output can be heavily modified using
283 commands like
284 @code{\override TextScript #'extra-offset = ( 1 . -1)}.  But
285 we have even more power if we use scheme.  For a full explantion
286 of this, see @ref{Interfaces for programmers}.
287
288 We can use scheme to simply @code{\override} commands,
289
290 @lilypond[quote,verbatim,ragged-right]
291 padText = #(define-music-function (parser location padding) (number?)
292 #{
293   \once \override TextScript #'padding = #$padding
294 #})
295
296 \relative c''' {
297   c4^"piu mosso" b a b
298   \padText #1.8
299   c4^"piu mosso" d e f
300   \padText #2.6
301   c4^"piu mosso" fis a g
302 }
303 @end lilypond
304
305 We can use it to create new commands,
306
307 @lilypond[quote,verbatim,ragged-right]
308 tempoMark = #(define-music-function
309   (parser location marktext padding) (string? number?)
310 #{
311   \once \override Score . RehearsalMark #'padding = $padding
312   \once \override Score . RehearsalMark #'no-spacing-rods = ##t
313   \mark \markup { \bold $marktext }
314 #})
315
316 \relative c'' {
317 c2 e
318 \tempoMark #"Allegro" #3.0
319 g c
320 }
321 @end lilypond
322
323 Even music expressions can be passed in.  Note that since we
324 want an articulation attached to the second variable, we
325 must #####.
326
327 @lilypond[quote,verbatim,ragged-right]
328 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
329 #{
330   $x e8 a b $y b a e
331 #})
332
333 \relative c''{
334   \pattern c8 c8\f
335   \pattern {d16 dis} { ais16-> b\p }
336 }
337 @end lilypond
338