1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @c This file is part of lilypond-learning.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.
16 NB: This chapter is still under development and this version is
17 somewhat experimental; nothing is fixed. Don't translate yet!
23 * The Internals Reference manual::
29 @section Tweaking basics
31 @q{Tweaking} is a LilyPond term for the various methods available
32 to the user for modifying the actions taken during interpretation
33 of the input file and modifying the appearance of the printed
34 output. Some tweaks are very easy to use; others are more
35 complex. But taken together the methods available for tweaking
36 permit almost any desired appearance of the printed music to be achieved.
38 In this section we cover the basic concepts required to understand
39 tweaking. Later we give a variety of potted commands which can
40 simply be copied to obtain the same effect in your own scores, and
41 at the same time we show how these commands may be constructed so
42 that you may learn how to develop your own tweaks.
44 Before starting on this Chapter you may wish to review the section
45 @ref{Contexts and engravers}, as Contexts, Engravers and the
46 Properties contained within them are fundamental to understanding
47 and constructing Tweaks.
50 * Objects and interfaces::
51 * Naming conventions of objects and properties::
55 @node Objects and interfaces
56 @subsection Objects and interfaces
63 Tweaking involves modifying the internal operation and structures
64 of the LilyPond program, so we must first introduce some terms
65 which are used to describe those internal operations and
68 The term @q{Object} is a generic term used to refer to the
69 multitude of internal structures built by LilyPond during the
70 processing of an input file. So when a command like @code{\new
71 Staff} is encountered a new object of type @code{Staff} is
72 constructed. That @code{Staff} object then holds all the
73 properties associated with that particular staff, for example, its
74 name and its key signature, together with details of the engravers
75 which have been assigned to operate within that staff's context.
76 Similarly, there are @code{Voice} objects, @code{Score} objects,
77 @code{Lyric} objects, and objects to represent barlines,
78 noteheads, ties, dynamics, etc, each with their own set of
81 Some types of object are given special names. Objects which
82 represent items of notation on the printed output such as
83 noteheads, stems, slurs, ties, fingering, clefs, etc are called
84 @q{Layout objects}, often known as @q{Graphical Objects}, or
85 @q{Grobs} for short. These are still objects in the generic sense
86 above, and so they too all have properties associated with them,
87 such as their position, size, color, etc.
89 Some layout objects are still more specialised. Phrasing slurs,
90 crescendo hairpins, ottavo marks, and many other grobs are not
91 localised in a single place -- they have a starting point, an
92 ending point, and maybe other properties concerned with their
93 shape. Objects with an extended shape like these are called
96 It remains to explain what @q{Interfaces} are. Many objects,
97 even though they are quite different, share common features
98 which need to be processed in the same way.
99 For example, all grobs have a color, a size, a position, etc,
100 and all these properties are processed in the same way during
102 interpretation of the input file. To simplify these internal
103 operations these common actions and properties are grouped
104 together in an object called a @code{grob-interface}. There
105 are many other groupings of common properties like this, each
106 one given a name ending in @code{-interface}. In total there
107 are over 100 such interfaces. We shall see later why this is
108 of interest and use to the user.
110 These, then, are the main terms relating to objects which we
111 shall use in this chapter.
113 @node Naming conventions of objects and properties
114 @subsection Naming conventions of objects and properties
116 We met some object naming conventions previously, in
117 @ref{Contexts and engravers}. Here for reference is a list
118 of the most common object types together with the conventions
119 for naming them and a couple of examples of some real names.
121 @multitable @columnfractions .33 .33 .33
122 @headitem Object type
123 @tab Naming convention
125 @item Contexts, Layout Objects
126 @tab Aaaa or AaaaAaaaAaaa
127 @tab Staff, GrandStaff,
129 @tab Aaaa_aaa_engraver
130 @tab Clef_engraver, Note_heads_engraver
132 @tab aaa-aaa-interface
133 @tab grob-interface, break-aligned-interface
134 @item Context Properties
135 @tab aaa or aaaAaaaAaaa
136 @tab alignAboveContext, skipBars
137 @item Layout Object Properties
138 @tab aaa or aaa-aaa-aaa
139 @tab direction, beam-thickness
142 As we shall see shortly, the properties of different types of
143 object are modified by different commands, so it is useful to
144 be able to recognise the type of object from the names of its
148 @node Tweaking methods
149 @subsection Tweaking methods
151 We have already met the commands @code{\set} and @code{\with},
152 used to change the properties of @strong{contexts} and to remove
154 engravers, in @ref{Modifying context properties} and @ref{Adding
155 and removing engravers}. We now must meet one more command.
157 The command to change the properties of @strong{layout objects} is
158 @code{\override}. Because this command has to modify
159 internal properties deep within LilyPond its syntax is not
160 as simple as the commands you have met so far. It needs to
161 know precisely which property of which object in which context
162 has to be modified, and what its new value is to be. Let's see
165 The general syntax of this command is:
168 \override @emph{context}.@emph{layout_object} #'@emph{layout_property} = #@emph{value}
172 This will set the property with the name @emph{layout_property}
173 of the layout object with the name
174 @emph{layout_object}, which is a member of the @emph{context}
175 context, to the value @emph{value}.
177 For now, don't worry about the @code{#'}, which must precede the
178 layout property, and the @code{#}, which must precede the value.
179 These must always be present in exactly this form. This is the
180 most common command used in tweaking, and most of the rest of
181 this chapter will be directed to presenting examples of how it is
184 Once overridden, the property retains its new value until it is
185 overridden again or a @code{\revert} command is encountered.
186 The @code{\revert} command has the following syntax and causes
187 the value of the property to revert to its original default
188 value; note, not its previous value if several @code{\override}
189 commands have been issued.
192 \revert @emph{context}.@emph{layout_object} #'@emph{layout_property}
195 There is another form of the override command,
196 @code{\overrideProperty}, which is occasionally required.
197 We mention it here for completeness, but for details see
198 @ruser{Difficult tweaks}.
200 The final tweaking command which is available is @code{\tweak}.
201 It is not really a new command but a shorthand for an
202 @code{\override} command which may be used in a few special
203 circumstances. Again, we shall not discuss or
204 use it here. You may find the details in
205 @ruser{Objects connected to the input}.
207 @node The Internals Reference manual
208 @section The Internals Reference manual
210 @cindex Internals Reference
213 * Properties of layout objects::
214 * Properties found in interfaces::
217 @node Properties of layout objects
218 @subsection Properties of layout objects
220 @cindex properties of layout objects
221 @cindex properties of grobs
222 @cindex grobs, properties of
223 @cindex layout objects, properties of
225 Suppose you have a slur in a score which, to your mind,
226 appears too thin and you'd like to draw it a little thicker.
227 How do you go about doing this? You know from the statements
228 earlier about the flexibility of LilyPond that such a thing
229 should be possible, and you would probably guess that an
230 @code{\override} command would be needed. But is there a
231 thickness property for a slur, and if there is, how might it
232 be modified? This is where the Internals Reference manual
233 comes in. It contains all the information you might need to
234 construct this and all other @code{\override} commands.
236 Before we look at the Internals Reference a word of warning.
237 This is a @strong{reference} document, which means there is
238 little or no explanation contained within it: its purpose is
239 to present information precisely and concisely. This
240 might mean it looks daunting at first sight. Don't worry!
241 The guidance and explanation presented here will enable you
242 to extract the information from the Internals Reference for
243 yourself with just a little practice.
245 @cindex override example
246 @cindex Internals Reference, example of using
248 Let's use a concrete example with a simple fragment of real
251 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
254 { r4 b8 b[( g]) g | g[( e]) e d[( f]) a | a g }
255 \addlyrics { The man who feels love's sweet e -- mo -- tion }
259 Suppose now that we decide we would like the slurs to be a
260 little heavier. Is this possible? The slur is certainly a
261 layout object, so the question is, @q{Is there a property
262 belonging to a slur which controls the heaviness?} To answer
263 this we must look in the Internals Reference, or IR for short.
265 The IR for the version of LilyPond you are using may be found
266 on the LilyPond website at http://lilypond.org. Go to the
267 documentation page and click on the Internals Reference link.
268 For learning purposes you should use the standard html version,
269 not the @q{one big page} or the PDF. For the next few
270 paragraphs to make sense you will need to actually do this
273 Under the heading @strong{Top} you will see five links. Select
274 the link to the @emph{Backend}, which is where information about
275 layout objects is to be found. There, under the heading
276 @strong{Backend}, select the link to @emph{All layout objects}.
277 The page that appears lists all the layout objects used in your
278 version of LilyPond, in alphabetic order. Select the link to
279 Slur, and the properties of Slurs are listed.
281 (An alternative way of finding this page is from the Notation
282 Reference. On one of the pages that deals with slurs you may
283 find a link to the Internals Reference. This link will
284 take you directly to this page, but often it is easier to go
285 straight to the IR and search there.)
287 This Slur page in the IR tells us first that Slur objects are
289 Slur_engraver. Then it lists the standard settings. Note
290 these are @strong{not} in alphabetic order. Browse down
291 them looking for a property that might control the heaviness
292 of slurs, and you should find
295 @code{thickness} (number)
297 Line thickness, generally measured in @code{line-thickness}
300 This tells us first that there @emph{is} a property that
301 controls thickness, that its value is a simple @emph{number},
302 that the default value is 1.2, and that the units are
303 in another property called @code{line-thickness}. This looks
304 a good bet to change the heaviness.
306 As we said earlier, there are few to no explanations in the IR,
307 but we already have enough information to try changing the
308 slur thickness. We see that the name of the layout object
309 is @code{Slur}, that the name of the property to change is
310 @code{thickness} and that the new value should be a number
311 somewhat larger than 1.2 if we are to make slurs thicker.
313 But what is the Context? We could guess that slurs are in
314 the Voice context, as they are clearly closely associated
315 with individual lines of music, but can we be sure? To
316 find out, go back to the top of the IR page describing the
317 Slur, where it says @q{Slur objects are created by: Slur
318 engraver}. So slurs will be created in whichever context
319 the @code{Slur_engraver} is in. Follow the link to the
320 @code{Slur_engraver} page. At the very bottom it tells
321 us that @code{Slur_engraver} is part of five Voice contexts,
322 including the standard voice context, @code{Voice}, so our
325 We can now construct the @code{\override} command by simply
326 substituting the values we have found for the names. Let's
327 use a very large value for the thickness at first, so we
328 can be sure the command is working. We get:
331 \override Voice.Slur #'thickness = #5.0
334 Don't forget the @code{#'} preceding the
335 property name and and @code{#} preceding the new value!
337 The final question is, @q{Where should this command be
338 placed?} While you are unsure and learning, the best
339 answer is, @q{Within the music, before the first slur and
340 close to it.} Let's do that:
342 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
346 % Increase thickness of all following slurs from 1.2 to 5.0
347 \override Voice.Slur #'thickness = #5.0
348 r4 b8 b[( g]) g | g[( e]) e d[( f]) a | a g
350 \addlyrics { The man who feels love's sweet e -- mo -- tion }
354 @cindex overriding once only
355 @cindex once override
358 As you can see, all the slurs are thicker. But, what if we
359 wanted just the first slur to be thicker? This is achieved
360 with the @code{\once} command. Placed immediately before
361 the @code{\override} command it causes it to affect only the
362 slur on the @strong{immediately following} note. If the
363 immediately following note does not have a slur the command
364 has no effect. So the command must be repositioned as follows:
366 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
371 % Increase thickness of immediately following slur only
372 \once \override Voice.Slur #'thickness = #5.0
373 b[( g]) g | g[( e]) e d[( f]) a | a g
375 \addlyrics { The man who feels love's sweet e -- mo -- tion }
379 Finally, what if we wanted just the first two slurs to be
380 heavier? Well, we could use two commands, each preceded by
381 @code{\once} placed immediately before each of the notes where
384 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
389 % Increase thickness of immediately following slur only
390 \once \override Voice.Slur #'thickness = #5.0
392 % Increase thickness of immediately following slur only
393 \once \override Voice.Slur #'thickness = #5.0
394 g[( e]) e d[( f]) a | a g
396 \addlyrics { The man who feels love's sweet e -- mo -- tion }
404 or we could omit the @code{\once} command and use the
405 @code{\revert} command
406 to return the @code{thickness} property to its default value:
408 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
413 % Increase thickness of all following slurs from 1.2 to 5.0
414 \override Voice.Slur #'thickness = #5.0
417 % Revert thickness of all following slurs to default of 1.2
418 \revert Voice.Slur #'thickness
421 \addlyrics { The man who feels love's sweet e -- mo -- tion }
426 The @code{\revert} command can be used to return any property
427 changed with @code{\override} back to its default value.
428 You may use whichever method best suits what you want to do.
430 That concludes our introduction to the IR, and the basic
431 method of tweaking. Several examples follow in the later
432 sections of this Chapter, but with progressively fewer words
433 of guidance and explanation.
435 @node Properties found in interfaces
436 @subsection Properties found in interfaces
438 @cindex interface properties
439 @cindex properties in interfaces
441 Suppose now that we wish to color a slur red. We would go
442 to the properties on Slurs in the IR as described in the
443 previous section, and look in vain, because there is nothing
444 there that looks like it might change the color. This is
445 because the color property is one that is common to all
446 layout objects, so, rather than including it in every layout
447 object, it is grouped together with other similar common
448 properties and placed in an @strong{Interface}, the
449 @code{grob-interface}. (Remember, grob is short for
450 @q{graphical object}, itself another name for a layout object.)
452 So now we need to learn how to find the properties of interfaces,
453 and to discover what objects use these interface properties.
455 Look again at the IR page which describes the Slur. At the
456 bottom of the page is a list of clickable (in the html versions
457 of the IT) interfaces which the Slur supports. The list has
458 three items: @code{spanner-interface}, @code{slur-interface}
459 and @code{grob-interface}.
461 The @code{spanner-interface} holds properties common to
462 spanners -- objects which extend over several notes --
465 The @code{slur-interface} holds properties common to ordinary
466 slurs and phrasing slurs.
468 The @code{grob-interface} holds properties common to all
469 layout objects, and it is here that you will find the
470 @code{color} property, which appears as
474 The color of this grob
480 @c The rest of this section is rubbish and will need to be rewritten -td
482 The value then is described as a @emph{list}? Why do we need
483 a list to specify a color? Well, we don't, but there are
484 several ways to specify a color and some of them do need a list.
485 See the Notation Reference @ruser{List of colors}. This shows
486 the @q{Normal colors} and the longer list of @q{X color names}.
487 The normal colors are written as a one-member list, which can
488 be written simply as @code{red}. But the X color names must be
489 written as a two-member list:
492 (x11-color 'LimeGreen)
496 where the first item in the list is always @q{x11-color} to
497 indicate this is a color from the longer list of X11 colors,
498 and the second item is the name of the color from the list
499 of X11 colors in the Notation Reference.
501 @cindex properties as lists
502 @cindex properties as text strings
504 This introduces two new concepts.
506 First the brackets round
507 this property value are required to form the two items into
508 a list, as required by the color property. Brackets would
509 generate an error if placed around a @q{normal color}, though,
510 because these are shorthand names known to LilyPond which
511 generate the appropriate list automatically.
513 Second, because the second
514 item is a text string it needs to be introduced with a
515 single apostrophe, @code{'}. This is why these apostrophes
516 are needed before @code{'thickness} and @code{'color'}.
517 These are both text strings too.
519 So, putting this into practice, we can change the second
520 slur to the normal color magenta and the third slur
521 to the X11 color, DarkOrange, where we have made all the
522 slurs thicker to show the colors better, as follows:
524 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
528 \override Voice.Slur #'thickness = #5.0
531 \once \override Voice.Slur #'color = #magenta
533 \once \override Voice.Slur #'color = #(x11-color 'DarkOrange)
536 \addlyrics { The man who feels love's sweet e -- mo -- tion }
543 @c Old stuff follows -td
546 @section Common tweaks
552 * Fixing overlapping notation::
553 * Other common tweaks::
554 * Fitting music onto fewer pages::
558 @subsection Moving objects
560 This may come as a surprise, but LilyPond is not perfect. Some notation
561 elements can overlap. This is unfortunate, but (in most cases) is easily
564 TODO: with the new spacing features in 2.12, these specific examples are no
565 longer relevant. However, they still demonstrate powerful features
566 of lilypond, so they remain until somebody creates some better examples.
568 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
569 % temporary code to break this example:
570 \override TextScript #'outside-staff-priority = ##f
571 e4^\markup{ \italic ritenuto } g b e
576 The easiest solution is to increase the distance between the object
577 (in this case text, but it could easily be fingerings or dynamics
578 instead) and the note. In LilyPond, this is called the
579 @code{padding} property; it is measured in staff spaces. For most
580 objects, this value is around 1.0 or less (it varies with each
581 object). We want to increase it, so let's try 1.5
583 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
584 % temporary code to break this example:
585 \override TextScript #'outside-staff-priority = ##f
586 \once \override TextScript #'padding = #1.5
587 e4^\markup{ \italic ritenuto } g b e
590 That looks better, but it isn't quite big enough. After experimenting
591 with a few values, we think 2.3 is the best number in this case. However,
592 this number is merely the result of experimentation and my personal
593 taste in notation. Try the above example with 2.3... but also try higher
594 (and lower) numbers. Which do you think looks the best?
596 The @code{staff-padding} property is closely related. @code{padding}
597 controls the minimum amount of space between an object and the nearest
598 other object (generally the note or the staff lines);
599 @code{staff-padding} controls the minimum amount of space between an
600 object and the staff. This is a subtle difference, but you can see
603 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
604 % temporary code to break this example:
605 \override TextScript #'outside-staff-priority = ##f
607 \once \override TextScript #'padding = #4.6
609 \once \override TextScript #'staff-padding = #4.6
610 c4^"piu mosso" fis a g
612 c'4^"piu mosso" b a b
613 \once \override TextScript #'padding = #4.6
615 \once \override TextScript #'staff-padding = #4.6
616 c4^"piu mosso" fis a g
621 Another solution gives us complete control over placing the object -- we
622 can move it horizontally or vertically. This is done with the
623 @code{extra-offset} property. It is slightly more complicated and can
624 cause other problems. When we move objects with @code{extra-offset},
625 the movement is done after LilyPond has placed all other objects. This
627 that the result can overlap with other objects.
629 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
630 % temporary code to break this example:
631 \override TextScript #'outside-staff-priority = ##f
632 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
633 e4^\markup{ \italic ritenuto } g b e
636 With @code{extra-offset}, the first number controls the horizontal
637 movement (left is negative); the second number controls the vertical
638 movement (up is positive). After a bit of experimenting, we decided
639 that these values look good
641 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
642 % temporary code to break this example:
643 \override TextScript #'outside-staff-priority = ##f
644 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
645 e4^\markup{ \italic ritenuto } g b e
649 Again, these numbers are simply the result of a few experiments and
650 looking at the output. You might prefer the text to be slightly higher,
651 or to the left, or whatever. Try it and look at the result!
653 One final warning: in this section, we used
656 \once \override TextScript @dots{}
659 This tweaks the display of text for the next note. If the note has
660 no text, this tweak does nothing (and does @strong{not} wait until
661 the next bit of text). To change the behavior of everything after
662 the command, omit the @code{\once}. To stop this tweak, use a
663 @code{\revert}. This is explained in depth in
664 @ruser{The \override command}.
666 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
667 % temporary code to break this example:
668 \override TextScript #'outside-staff-priority = ##f
670 \once \override TextScript #'padding = #4.6
673 \once \override TextScript #'padding = #4.6
677 \override TextScript #'padding = #4.6
680 \revert TextScript #'padding
686 This manual: @ruser{The \override command}, @ref{Common tweaks}.
689 @node Fixing overlapping notation
690 @subsection Fixing overlapping notation
692 In @ref{Moving objects}, we saw how to move a @code{TextScript}
693 object. The same mechanism can be used to move other types of
694 objects; simply replace @code{TextScript} with the name of
697 To find the object name, look at the @q{@strong{see also}} at
698 bottom of the relevant documentation page. For example, at
699 the bottom of @ruser{Dynamics}, we see
704 Internals Reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
705 Vertical positioning of these symbols is handled by
706 @internalsref{DynamicLineSpanner}.
710 So to move dynamics around vertically, we use
713 \override DynamicLineSpanner #'padding = #2.0
716 We cannot list every object, but here is a list of the most
719 @multitable @columnfractions .33 .66
720 @headitem Object type @tab Object name
721 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
722 @item Dynamics (horizontally) @tab @code{DynamicText}
723 @item Ties @tab @code{Tie}
724 @item Slurs @tab @code{Slur}
725 @item Articulations @tab @code{Script}
726 @item Fingerings @tab @code{Fingering}
727 @item Text e.g. @code{^"text"} @tab @code{TextScript}
728 @item Rehearsal / Text marks @tab @code{RehearsalMark}
732 @node Other common tweaks
733 @subsection Other common tweaks
735 Some overrides are so common that predefined commands are provided as
736 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
737 commands are described in the Notation Reference under the appropriate
740 The complete list of modifications available for each type of
741 object (like slurs or beams) are documented in the Program
742 Reference. However, many layout objects share properties which can be
743 used to apply generic tweaks.
750 The @code{padding} property can be set to increase
751 (or decrease) the distance between symbols that are printed
752 above or below notes. This applies to all objects with
753 @code{side-position-interface}.
755 @lilypond[quote,fragment,relative=1,verbatim]
757 \override Script #'padding = #3
761 @lilypond[quote,fragment,relative=1,verbatim]
762 % This will not work, see below:
763 \override MetronomeMark #'padding = #3
767 \override Score.MetronomeMark #'padding = #3
772 Note in the second example how important it is to figure out what
773 context handles a certain object. Since the @code{MetronomeMark} object
774 is handled in the @code{Score} context, property changes in the
775 @code{Voice} context will not be noticed. For more details, see
776 @ruser{Constructing a tweak}.
781 The @code{extra-offset} property moves objects around
782 in the output; it requires a pair of numbers. The first number
783 controls horizontal movement; a positive number will
784 move the object to the right. The second number controls vertical
785 movement; a positive number will move it higher. The
786 @code{extra-offset} property is a low-level feature: the
787 formatting engine is completely oblivious to these offsets.
789 In the following example, the second fingering is moved a little to
790 the left, and 1.8 staff space downwards:
792 @lilypond[quote,fragment,relative=1,verbatim]
795 \once \override Fingering
796 #'extra-offset = #'(-0.3 . -1.8)
801 Setting the @code{transparent} property will cause an object to be printed
802 in @q{invisible ink}: the object is not printed, but all its other
803 behavior is retained. The object still takes up space, it takes part in
804 collisions, and slurs, ties, and beams can be attached to it.
806 @cindex transparent objects
807 @cindex removing objects
808 @cindex hiding objects
809 @cindex invisible objects
810 The following example demonstrates how to connect different voices
811 using ties. Normally, ties only connect two notes in the same
812 voice. By introducing a tie in a different voice,
814 @lilypond[quote,fragment,relative=2]
823 and blanking the first up-stem in that voice, the tie appears to cross
827 @lilypond[quote,fragment,relative=2,verbatim]
829 \once \override Stem #'transparent = ##t
836 To make sure that the just-blanked stem doesn't squeeze the tie too much,
837 we also lengthen the stem, by setting the @code{length} to
840 @lilypond[quote,fragment,relative=2,verbatim]
842 \once \override Stem #'transparent = ##t
843 \once \override Stem #'length = #8
852 @cindex Tweaks, distances
855 Distances in LilyPond are measured in staff-spaces, while most
856 thickness properties are measured in line-thickness. Some
857 properties are different; for example, the thickness of beams
858 are measured in staff-spaces. For more information, see the
859 relevant portion of the program reference.
862 @node Fitting music onto fewer pages
863 @subsection Fitting music onto fewer pages
865 Sometimes you can end up with one or two staves on a second
866 (or third, or fourth...) page. This is annoying, especially
867 if you look at previous pages and it looks like there is plenty
868 of room left on those.
870 When investigating layout issues, @code{annotate-spacing} is
871 an invaluable tool. This command prints the values of various
872 layout spacing commands; see @ruser{Displaying spacing}, for more
873 details. From the output of @code{annotate-spacing}, we can
874 see which margins we may wish to alter.
876 Other than margins, there are a few other options to save space:
880 You may tell LilyPond to place systems as close together as
881 possible (to fit as many systems as possible onto a page), but
882 then to space those systems out so that there is no blank
883 space at the bottom of the page.
887 between-system-padding = #0.1
888 between-system-space = #0.1
889 ragged-last-bottom = ##f
895 You may force the number of systems (i.e., if LilyPond wants
896 to typeset some music with 11 systems, you could force it to
906 Avoid (or reduce) objects which increase the vertical size of
907 a system. For example, volta repeats (or alternate repeats)
908 require extra space. If these repeats are spread over two
909 systems, they will take up more space than one system with
910 the volta repeats and another system without.
912 Another example is moving dynamics which @q{stick out} of
915 @lilypond[verbatim,quote,fragment]
918 \override DynamicLineSpanner #'padding = #-1.8
919 \override DynamicText #'extra-offset = #'( -2.1 . 0)
925 Alter the horizontal spacing via @code{SpacingSpanner}. See
926 @ruser{Changing horizontal spacing}, for more details.
928 @lilypond[verbatim,quote]
931 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
932 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
933 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
934 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
939 \override SpacingSpanner
940 #'base-shortest-duration = #(ly:make-moment 1 4)
949 @node TODO other name
950 @section TODO other name
953 * Predefined tweaks::
954 * Advanced tweaks with Scheme::
955 * Avoiding tweaks with slower processing::
956 * The three methods of tweaking::
959 @node Predefined tweaks
960 @subsection Predefined tweaks
962 TODO: Some tweaks are really common, blah blah.
964 for example \slurUp, \fatText.
966 Show example, then explain where to find ly/propert-ly.
969 The Internals Reference documentation contains a lot of information
970 about LilyPond, but even more information can be gathered from
971 looking at the internal LilyPond files.
973 Some default settings (such as the definitions for
974 @code{\header@{@}}s) are stored as @code{.ly} files. Other
975 settings (such as the definitions of markup commands) are
976 stored as @code{.scm} (Scheme) files. Further explanation is
977 outside the scope of this manual; users should be warned that
978 a substantial amount of technical knowledge or time is required
979 to understand these files.
983 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
986 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
987 To access this, either @code{cd} into this directory from the
988 Terminal, or control-click on the LilyPond application and select
989 @q{Show Package Contents}.
991 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
995 The @file{ly/} and @file{scm/} directories will be of
996 particular interest. Files such as @file{ly/property-init.ly} and
997 @file{ly/declarations-init.ly} define all the common tweaks.
1000 @node Advanced tweaks with Scheme
1001 @subsection Advanced tweaks with Scheme
1003 We have seen how LilyPond output can be heavily modified using
1005 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
1006 we have even more power if we use Scheme. For a full explantion
1007 of this, see the @ref{Scheme tutorial}, and
1008 @ruser{Interfaces for programmers}.
1010 We can use Scheme to simply @code{\override} commands,
1012 @lilypond[quote,verbatim,ragged-right]
1013 padText = #(define-music-function (parser location padding) (number?)
1015 \once \override TextScript #'padding = #$padding
1019 c4^"piu mosso" b a b
1021 c4^"piu mosso" d e f
1023 c4^"piu mosso" fis a g
1027 We can use it to create new commands,
1029 @lilypond[quote,verbatim,ragged-right]
1030 tempoMark = #(define-music-function (parser location padding marktext)
1033 \once \override Score . RehearsalMark #'padding = $padding
1034 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
1035 \mark \markup { \bold $marktext }
1040 \tempoMark #3.0 #"Allegro"
1045 Even music expressions can be passed in.
1047 @lilypond[quote,verbatim,ragged-right]
1048 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
1055 \pattern {d16 dis} { ais16-> b\p }
1060 @node Avoiding tweaks with slower processing
1061 @subsection Avoiding tweaks with slower processing
1063 LilyPond can perform extra checks while it processes files. These
1064 commands will take extra time, but the result may require fewer
1068 %% makes sure text scripts and lyrics are within the paper margins
1069 \override Score.PaperColumn #'keep-inside-line = ##t
1070 \override Score.NonMusicalPaperColumn #'keep-inside-line = ##t
1073 In some cases (see issue 246), this must be done before
1074 @code{\override} commands can be processed.
1078 \override PaperColumn #'keep-inside-line = ##t
1079 \override NonMusicalPaperColumn #'keep-inside-line = ##t
1086 @node The three methods of tweaking
1087 @subsection The three methods of tweaking
1109 FIXME discuss \tweak
1113 FIXME: Move the following words and example into Tweaks or
1114 somewhere more suitable, leaving just a ref here. -td
1116 Ways of correcting horizontal placings are described fully
1117 in the Notation Reference.
1118 We introduce just one here, the @code{force-hshift} property of
1119 @code{NoteColumn}. The lower two notes of the first chord (i.e,
1120 those in the third voice) should not be shifted away from the
1121 note column of the higher two notes. To correct this we set
1122 @code{force-hshift} of these notes to zero.
1123 The lower note of the second chord is best placed just to the
1124 right of the higher notes. We achieve this by setting
1125 @code{force-hshift} of this note to 0.5, ie half a notehead's
1126 width to the right of the note column of the higher notes.
1128 Here's the final result:
1130 @lilypond[quote,verbatim,fragment,ragged-right]
1131 \new Staff \relative c'' {
1134 { c2 aes4. bes8 } \\
1137 \once \override NoteColumn #'force-hshift = #0 <ees c>2
1138 \once \override NoteColumn #'force-hshift = #0.5 des2
1149 - There is a section in the manual on \set vs \override (3.3.7),
1150 which is incomplete. First it doesn't mention \overrideProperty,
1151 nor does it mention properties which are not capitalized at all.
1152 And it should explain that \override should be used to set
1153 properties with hyphenated names, like auto-knee-gap. (I had to
1154 experiment to find out how to do this.)
1157 FIXME: moved from fundamental, dumped here at random.
1159 @lilypond[verbatim,quote,ragged-right]
1160 \new Staff = "main" {
1164 << % Start main and ossia in parallel
1165 { r8 f c c } % Main music
1166 \new Staff \with { % Start ossia staff
1167 \remove "Clef_engraver"
1168 \remove "Time_signature_engraver"
1169 % Reduce size of notes and staff
1171 \override StaffSymbol #'staff-space = #(magstep -2)
1172 alignAboveContext = "main" % Place above main staff
1174 { s8 f f c } % Ossia music
1175 >> % End parallel music