Documentation/user/tweaks.itely

   1 @c -*- coding: utf-8; mode: texinfo; -*-
   2 @node Tweaking output
   3 @chapter Tweaking output
   4
   5 Tweak explanation.
   6
   7
   8 @menu
   9 * Fixing overlapping notation::
  10 * Common tweaks::
  11 * Advanced tweaks with scheme::
  12 @end menu
  13
  14
  15 @node Fixing overlapping notation
  16 @section Fixing overlapping notation
  17
  18 This may come as a surprise, but LilyPond isn't perfect.  Some notation
  19 elements can overlap.  This is unfortunate, but (in most cases) is easily
  20 solved.
  21
  22 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
  23 e4^\markup{ \italic ritenuto } g b e
  24 @end lilypond
  25
  26 @cindex padding
  27
  28 The easiest solution is to increase the distance between the object
  29 (in this case text, but it could easily be fingerings or dynamics
  30 instead) and the note.  In LilyPond, this is called the
  31 @code{padding} property; it is measured in staff spaces.  For most
  32 objects, this value is around 1.0 or less (it varies with each
  33 object). We want to increase it, so let's try 1.5
  34
  35 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
  36 \once \override TextScript #'padding = #1.5
  37 e4^\markup{ \italic ritenuto } g b e
  38 @end lilypond
  39
  40 That looks better, but it isn't quite big enough.  After experimenting
  41 with a few values, we think 2.3 is the best number in this case.  However,
  42 this number is merely the result of experimentation and my personal
  43 taste in notation.  Try the above example with 2.3... but also try higher
  44 (and lower) numbers.  Which do you think looks the best?
  45
  46 The @code{staff-padding} property is closely related.  @code{padding}
  47 controls the minimum amount of space between an object and the nearest
  48 other object (generally the note or the staff lines);
  49 @code{staff-padding} controls the minimum amount of space between an
  50 object and the staff.  This is a subtle difference, but you can see
  51 the behavior here.
  52
  53 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
  54 c4^"piu mosso" b a b
  55 \once \override TextScript #'padding = #2.6
  56 c4^"piu mosso" d e f
  57 \once \override TextScript #'staff-padding = #2.6
  58 c4^"piu mosso" fis a g
  59 \break
  60 c,,4^"piu mosso" b a b
  61 \once \override TextScript #'padding = #2.6
  62 c4^"piu mosso" d e f
  63 \once \override TextScript #'staff-padding = #2.6
  64 c4^"piu mosso" fis a g
  65 @end lilypond
  66
  67 @cindex extra-offset
  68
  69 Another solution gives us complete control over placing the object -- we
  70 can move it horizontally or vertically.  This is done with the
  71 @code{extra-offset} property.  It is slightly more complicated and can
  72 cause other problems.  When we move objects with @code{extra-offset},
  73 the movement is done after LilyPond has placed all other objects.  This means
  74 that the result can overlap with other objects.
  75
  76 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
  77 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
  78 e4^\markup{ \italic ritenuto } g b e
  79 @end lilypond
  80
  81 With @code{extra-offset}, the first number controls the horizontal
  82 movement (left is negative); the second number controls the vertical
  83 movement (up is positive).  After a bit of experimenting, we decided
  84 that these values look good
  85
  86 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
  87 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
  88 e4^\markup{ \italic ritenuto } g b e
  89 @end lilypond
  90
  91 @noindent
  92 Again, these numbers are simply the result of a few experiments and
  93 looking at the output.  You might prefer the text to be slightly higher,
  94 or to the left, or whatever.  Try it and look at the result!
  95
  96 One final warning: in this section, we used
  97
  98 @example
  99 \once \override TextScript @dots{}
 100 @end example
 101
 102 This tweaks the display of text for the next note.  If the note has
 103 no text, this tweak does nothing (and does @strong{not} wait until
 104 the next bit of text).
 105
 106 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
 107 c4^"piu mosso" b
 108 \once \override TextScript #'padding = #2.6
 109   a4 b
 110 c4^"piu mosso" d e f
 111 \once \override TextScript #'padding = #2.6
 112 c4^"piu mosso" d e f
 113 c4^"piu mosso" d e f
 114 \break
 115 \override TextScript #'padding = #2.6
 116 c4^"piu mosso" d e f
 117 c4^"piu mosso" d e f
 118 @end lilypond
 119
 120
 121 @seealso
 122
 123 This manual: @ref{The \override command}, @ref{Common tweaks}.
 124
 125
 126 @menu
 127 * Common tweaks::
 128 @end menu
 129
 130 @node Common tweaks
 131 @section Common tweaks
 132
 133 @c  Should we point at ly/property-init.ly ?  -gp
 134 Some overrides are so common that predefined commands are provided as
 135 short-cuts, for example, @code{\slurUp} and @code{\stemDown}.  These
 136 commands are described in
 137 @ifhtml
 138 the
 139 @end ifhtml
 140 @c @ref{Notation manual},
 141 Notation manual
 142 @c FIXME
 143 under the sections for slurs and stems
 144 respectively.
 145
 146 The exact tuning possibilities for each type of layout object are
 147 documented in the program reference of the respective
 148 object.  However, many layout objects share properties, which can be
 149 used to apply generic tweaks.  We mention a few of these:
 150
 151 @itemize @bullet
 152 @item The @code{extra-offset} property, which
 153 @cindex @code{extra-offset}
 154 has a pair of numbers as value, moves objects around in the printout.
 155 The first number controls left-right movement; a positive number will
 156 move the object to the right.  The second number controls up-down
 157 movement; a positive number will move it higher.  The units of these
 158 offsets are staff-spaces.  The @code{extra-offset} property is a
 159 low-level feature: the formatting engine is completely oblivious to
 160 these offsets.
 161
 162 In the following example, the second fingering is moved a little to
 163 the left, and 1.8 staff space downwards:
 164
 165 @cindex setting object properties
 166
 167 @lilypond[quote,fragment,relative=1,verbatim]
 168 \stemUp
 169 f-5
 170 \once \override Fingering
 171     #'extra-offset = #'(-0.3 . -1.8)
 172 f-5
 173 @end lilypond
 174
 175 @item
 176 Setting the @code{transparent} property will cause an object to be printed
 177 in `invisible ink': the object is not printed, but all its other
 178 behavior is retained.  The object still takes up space, it takes part in
 179 collisions, and slurs, ties, and beams can be attached to it.
 180
 181 @cindex transparent objects
 182 @cindex removing objects
 183 @cindex hiding objects
 184 @cindex invisible objects
 185 The following example demonstrates how to connect different voices
 186 using ties.  Normally, ties only connect two notes in the same
 187 voice.  By introducing a tie in a different voice,
 188
 189 @lilypond[quote,fragment,relative=2]
 190 << {
 191   b8~ b8\noBeam
 192 } \\ {
 193   b[ g8]
 194 } >>
 195 @end lilypond
 196
 197 @noindent
 198 and blanking the first up-stem in that voice, the tie appears to cross
 199 voices:
 200
 201 @lilypond[quote,fragment,relative=2,verbatim]
 202 << {
 203   \once \override Stem #'transparent = ##t
 204   b8~ b8\noBeam
 205 } \\ {
 206   b[ g8]
 207 } >>
 208 @end lilypond
 209
 210 @item
 211 The @code{padding} property for objects with
 212 @cindex @code{padding}
 213 @code{side-position-interface} can be set to increase the distance between
 214 symbols that are printed above or below notes.  We provide two
 215 examples; a more elaborate explanation is in @ref{Constructing a
 216 tweak}:
 217
 218 @lilypond[quote,fragment,relative=1,verbatim]
 219 c2\fermata
 220 \override Script #'padding = #3
 221 b2\fermata
 222 @end lilypond
 223
 224 @lilypond[quote,fragment,relative=1,verbatim]
 225 % This will not work, see below:
 226 \override MetronomeMark #'padding = #3
 227 \tempo 4=120
 228 c1
 229 % This works:
 230 \override Score.MetronomeMark #'padding = #3
 231 \tempo 4=80
 232 d1
 233 @end lilypond
 234
 235 Note in the second example how important it is to figure out what
 236 context handles a certain object. Since the @code{MetronomeMark} object
 237 is handled in the Score context, property changes in the @code{Voice}
 238 context will not be noticed.
 239
 240 @end itemize
 241
 242 Some tweakable options are called ``subproperties'' and reside inside
 243 properties.  To tweak those, use
 244
 245 @example
 246 \override Stem #'details #'beamed-lengths = #'(4 4 3)
 247 @end example
 248
 249 @cindex Tweaks, distances
 250 @cindex Distances
 251
 252 Distances in LilyPond are measured in staff-spaces, while most
 253 thickness properties are measured in line-thickness.  Some
 254 properties are different; for example, the thickness of beams
 255 is measured in staff-spaces.  For more information, see the
 256 relevant portion of the program reference.
 257
 258 More specific overrides are also possible.  The next section
 259 discusses in depth how to figure out these statements for yourself.
 260
 261
 262 @node Advanced tweaks with scheme
 263 @section Advanced tweaks with scheme
 264
 265 We have seen how LilyPond output can be heavily modified using
 266 commands like
 267 @code{\override TextScript #'extra-offset = ( 1 . -1)}.  But
 268 we have even more power if we use scheme.
 269
 270 FIXME scheme stuffs
 271