@c -*- coding: utf-8; mode: texinfo; -*- @node Tweaking output @chapter Tweaking output Tweak explanation. @menu * Fixing overlapping notation:: * Common tweaks:: * Advanced tweaks with scheme:: @end menu @node Fixing overlapping notation @section Fixing overlapping notation This may come as a surprise, but LilyPond isn't perfect. Some notation elements can overlap. This is unfortunate, but (in most cases) is easily solved. @lilypond[quote,fragment,ragged-right,verbatim,relative=2] e4^\markup{ \italic ritenuto } g b e @end lilypond @cindex padding The easiest solution is to increase the distance between the object (in this case text, but it could easily be fingerings or dynamics instead) and the note. In LilyPond, this is called the @code{padding} property; it is measured in staff spaces. For most objects, this value is around 1.0 or less (it varies with each object). We want to increase it, so let's try 1.5 @lilypond[quote,fragment,ragged-right,verbatim,relative=2] \once \override TextScript #'padding = #1.5 e4^\markup{ \italic ritenuto } g b e @end lilypond That looks better, but it isn't quite big enough. After experimenting with a few values, we think 2.3 is the best number in this case. However, this number is merely the result of experimentation and my personal taste in notation. Try the above example with 2.3... but also try higher (and lower) numbers. Which do you think looks the best? The @code{staff-padding} property is closely related. @code{padding} controls the minimum amount of space between an object and the nearest other object (generally the note or the staff lines); @code{staff-padding} controls the minimum amount of space between an object and the staff. This is a subtle difference, but you can see the behavior here. @lilypond[quote,fragment,ragged-right,verbatim,relative=2] c4^"piu mosso" b a b \once \override TextScript #'padding = #2.6 c4^"piu mosso" d e f \once \override TextScript #'staff-padding = #2.6 c4^"piu mosso" fis a g \break c,,4^"piu mosso" b a b \once \override TextScript #'padding = #2.6 c4^"piu mosso" d e f \once \override TextScript #'staff-padding = #2.6 c4^"piu mosso" fis a g @end lilypond @cindex extra-offset Another solution gives us complete control over placing the object -- we can move it horizontally or vertically. This is done with the @code{extra-offset} property. It is slightly more complicated and can cause other problems. When we move objects with @code{extra-offset}, the movement is done after LilyPond has placed all other objects. This means that the result can overlap with other objects. @lilypond[quote,fragment,ragged-right,verbatim,relative=2] \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 ) e4^\markup{ \italic ritenuto } g b e @end lilypond With @code{extra-offset}, the first number controls the horizontal movement (left is negative); the second number controls the vertical movement (up is positive). After a bit of experimenting, we decided that these values look good @lilypond[quote,fragment,ragged-right,verbatim,relative=2] \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 ) e4^\markup{ \italic ritenuto } g b e @end lilypond @noindent Again, these numbers are simply the result of a few experiments and looking at the output. You might prefer the text to be slightly higher, or to the left, or whatever. Try it and look at the result! One final warning: in this section, we used @example \once \override TextScript @dots{} @end example This tweaks the display of text for the next note. If the note has no text, this tweak does nothing (and does @strong{not} wait until the next bit of text). @lilypond[quote,fragment,ragged-right,verbatim,relative=3] c4^"piu mosso" b \once \override TextScript #'padding = #2.6 a4 b c4^"piu mosso" d e f \once \override TextScript #'padding = #2.6 c4^"piu mosso" d e f c4^"piu mosso" d e f \break \override TextScript #'padding = #2.6 c4^"piu mosso" d e f c4^"piu mosso" d e f @end lilypond @seealso This manual: @ref{The \override command}, @ref{Common tweaks}. @menu * Common tweaks:: @end menu @node Common tweaks @section Common tweaks @c Should we point at ly/property-init.ly ? -gp Some overrides are so common that predefined commands are provided as short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These commands are described in @ifhtml the @end ifhtml @c @ref{Notation manual}, Notation manual @c FIXME under the sections for slurs and stems respectively. The exact tuning possibilities for each type of layout object are documented in the program reference of the respective object. However, many layout objects share properties, which can be used to apply generic tweaks. We mention a few of these: @itemize @bullet @item The @code{extra-offset} property, which @cindex @code{extra-offset} has a pair of numbers as value, moves objects around in the printout. The first number controls left-right movement; a positive number will move the object to the right. The second number controls up-down movement; a positive number will move it higher. The units of these offsets are staff-spaces. The @code{extra-offset} property is a low-level feature: the formatting engine is completely oblivious to these offsets. In the following example, the second fingering is moved a little to the left, and 1.8 staff space downwards: @cindex setting object properties @lilypond[quote,fragment,relative=1,verbatim] \stemUp f-5 \once \override Fingering #'extra-offset = #'(-0.3 . -1.8) f-5 @end lilypond @item Setting the @code{transparent} property will cause an object to be printed in `invisible ink': the object is not printed, but all its other behavior is retained. The object still takes up space, it takes part in collisions, and slurs, ties, and beams can be attached to it. @cindex transparent objects @cindex removing objects @cindex hiding objects @cindex invisible objects The following example demonstrates how to connect different voices using ties. Normally, ties only connect two notes in the same voice. By introducing a tie in a different voice, @lilypond[quote,fragment,relative=2] << { b8~ b8\noBeam } \\ { b[ g8] } >> @end lilypond @noindent and blanking the first up-stem in that voice, the tie appears to cross voices: @lilypond[quote,fragment,relative=2,verbatim] << { \once \override Stem #'transparent = ##t b8~ b8\noBeam } \\ { b[ g8] } >> @end lilypond @item The @code{padding} property for objects with @cindex @code{padding} @code{side-position-interface} can be set to increase the distance between symbols that are printed above or below notes. We provide two examples; a more elaborate explanation is in @ref{Constructing a tweak}: @lilypond[quote,fragment,relative=1,verbatim] c2\fermata \override Script #'padding = #3 b2\fermata @end lilypond @lilypond[quote,fragment,relative=1,verbatim] % This will not work, see below: \override MetronomeMark #'padding = #3 \tempo 4=120 c1 % This works: \override Score.MetronomeMark #'padding = #3 \tempo 4=80 d1 @end lilypond Note in the second example how important it is to figure out what context handles a certain object. Since the @code{MetronomeMark} object is handled in the Score context, property changes in the @code{Voice} context will not be noticed. @end itemize Some tweakable options are called ``subproperties'' and reside inside properties. To tweak those, use @example \override Stem #'details #'beamed-lengths = #'(4 4 3) @end example @cindex Tweaks, distances @cindex Distances Distances in LilyPond are measured in staff-spaces, while most thickness properties are measured in line-thickness. Some properties are different; for example, the thickness of beams is measured in staff-spaces. For more information, see the relevant portion of the program reference. More specific overrides are also possible. The next section discusses in depth how to figure out these statements for yourself. @node Advanced tweaks with scheme @section Advanced tweaks with scheme We have seen how LilyPond output can be heavily modified using commands like @code{\override TextScript #'extra-offset = ( 1 . -1)}. But we have even more power if we use scheme. FIXME scheme stuffs