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 and property types together with
120 for naming them and a couple of examples of some real names.
122 @multitable @columnfractions .33 .33 .33
123 @headitem Object/property type
124 @tab Naming convention
126 @item Contexts, Layout Objects
127 @tab Aaaa or AaaaAaaaAaaa
128 @tab Staff, GrandStaff,
130 @tab Aaaa_aaa_engraver
131 @tab Clef_engraver, Note_heads_engraver
133 @tab aaa-aaa-interface
134 @tab grob-interface, break-aligned-interface
135 @item Context Properties
136 @tab aaa or aaaAaaaAaaa
137 @tab alignAboveContext, skipBars
138 @item Layout Object Properties
139 @tab aaa or aaa-aaa-aaa
140 @tab direction, beam-thickness
143 As we shall see shortly, the properties of different types of
144 object are modified by different commands, so it is useful to
145 be able to recognise the type of object from the names of its
149 @node Tweaking methods
150 @subsection Tweaking methods
152 We have already met the commands @code{\set} and @code{\with},
153 used to change the properties of @strong{contexts} and to remove
155 engravers, in @ref{Modifying context properties} and @ref{Adding
156 and removing engravers}. We now must meet one more command.
158 The command to change the properties of @strong{layout objects} is
159 @code{\override}. Because this command has to modify
160 internal properties deep within LilyPond its syntax is not
161 as simple as the commands you have met so far. It needs to
162 know precisely which property of which object in which context
163 has to be modified, and what its new value is to be. Let's see
166 The general syntax of this command is:
169 \override @emph{context}.@emph{layout_object} #'@emph{layout_property} = #@emph{value}
173 This will set the property with the name @emph{layout_property}
174 of the layout object with the name
175 @emph{layout_object}, which is a member of the @emph{context}
176 context, to the value @emph{value}.
178 The @emph{context} can be omitted in many situations, and in fact
179 must be omitted in some.
180 @c Eg: Context must not be present when overriding LyricText
181 @c properties within a \lyricsto block.
182 It can be omitted when the context is one of lowest level
183 contexts, i.e., @code{Voice} or @code{Lyrics}, and we shall omit
184 it in the following examples. Later we shall see when it must be
187 For now, don't worry about the @code{#'}, which must precede the
188 layout property, and the @code{#}, which must precede the value.
189 These must always be present in exactly this form. This is the
190 most common command used in tweaking, and most of the rest of
191 this chapter will be directed to presenting examples of how it is
194 Once overridden, the property retains its new value until it is
195 overridden again or a @code{\revert} command is encountered.
196 The @code{\revert} command has the following syntax and causes
197 the value of the property to revert to its original default
198 value; note, not its previous value if several @code{\override}
199 commands have been issued.
202 \revert @emph{context}.@emph{layout_object} #'@emph{layout_property}
205 Again, the @emph{context} will be omitted for now.
207 There is another form of the override command,
208 @code{\overrideProperty}, which is occasionally required.
209 We mention it here for completeness, but for details see
210 @ruser{Difficult tweaks}.
212 The final tweaking command which is available is @code{\tweak}.
213 It is not really a new command but a shorthand for an
214 @code{\override} command which must be used in a few special
215 circumstances. Again, we shall not discuss or use it here.
216 You may find the details in
217 @ruser{Objects connected to the input}.
219 @node The Internals Reference manual
220 @section The Internals Reference manual
222 @cindex Internals Reference
225 * Properties of layout objects::
226 * Properties found in interfaces::
227 * Types of properties::
230 @node Properties of layout objects
231 @subsection Properties of layout objects
233 @cindex properties of layout objects
234 @cindex properties of grobs
235 @cindex grobs, properties of
236 @cindex layout objects, properties of
238 Suppose you have a slur in a score which, to your mind,
239 appears too thin and you'd like to draw it a little heavier.
240 How do you go about doing this? You know from the statements
241 earlier about the flexibility of LilyPond that such a thing
242 should be possible, and you would probably guess that an
243 @code{\override} command would be needed. But is there a
244 heaviness property for a slur, and if there is, how might it
245 be modified? This is where the Internals Reference manual
246 comes in. It contains all the information you might need to
247 construct this and all other @code{\override} commands.
249 Before we look at the Internals Reference a word of warning.
250 This is a @strong{reference} document, which means there is
251 little or no explanation contained within it: its purpose is
252 to present information precisely and concisely. This
253 might mean it looks daunting at first sight. Don't worry!
254 The guidance and explanation presented here will enable you
255 to extract the information from the Internals Reference for
256 yourself with just a little practice.
258 @cindex override example
259 @cindex Internals Reference, example of using
261 Let's use a concrete example with a simple fragment of real
264 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
267 { r4 b8 b[( g]) g | g[( e]) e d[( f]) a | a g }
268 \addlyrics { The man who feels love's sweet e -- mo -- tion }
272 Suppose now that we decide we would like the slurs to be a
273 little heavier. Is this possible? The slur is certainly a
274 layout object, so the question is, @q{Is there a property
275 belonging to a slur which controls the heaviness?} To answer
276 this we must look in the Internals Reference, or IR for short.
278 The IR for the version of LilyPond you are using may be found
279 on the LilyPond website at http://lilypond.org. Go to the
280 documentation page and click on the Internals Reference link.
281 For learning purposes you should use the standard html version,
282 not the @q{one big page} or the PDF. For the next few
283 paragraphs to make sense you will need to actually do this
286 Under the heading @strong{Top} you will see five links. Select
287 the link to the @emph{Backend}, which is where information about
288 layout objects is to be found. There, under the heading
289 @strong{Backend}, select the link to @emph{All layout objects}.
290 The page that appears lists all the layout objects used in your
291 version of LilyPond, in alphabetic order. Select the link to
292 Slur, and the properties of Slurs are listed.
294 (An alternative way of finding this page is from the Notation
295 Reference. On one of the pages that deals with slurs you may
296 find a link to the Internals Reference. This link will
297 take you directly to this page, but often it is easier to go
298 straight to the IR and search there.)
300 This Slur page in the IR tells us first that Slur objects are
302 Slur_engraver. Then it lists the standard settings. Note
303 these are @strong{not} in alphabetic order. Browse down
304 them looking for a property that might control the heaviness
305 of slurs, and you should find
308 @code{thickness} (number)
310 Line thickness, generally measured in @code{line-thickness}
313 This tells us first that there @emph{is} a property that
314 controls thickness, that its value is a simple @emph{number},
315 that the default value is 1.2, and that the units are
316 in another property called @code{line-thickness}. This looks
317 a good bet to change the heaviness.
319 As we said earlier, there are few to no explanations in the IR,
320 but we already have enough information to try changing the
321 slur thickness. We see that the name of the layout object
322 is @code{Slur}, that the name of the property to change is
323 @code{thickness} and that the new value should be a number
324 somewhat larger than 1.2 if we are to make slurs thicker.
326 We can now construct the @code{\override} command by simply
327 substituting the values we have found for the names, omitting
328 the context. Let's use a very large value for the thickness
329 at first, so we can be sure the command is working. We get:
332 \override Slur #'thickness = #5.0
335 Don't forget the @code{#'} preceding the
336 property name and and @code{#} preceding the new value!
338 The final question is, @q{Where should this command be
339 placed?} While you are unsure and learning, the best
340 answer is, @q{Within the music, before the first slur and
341 close to it.} Let's do that:
343 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
347 % Increase thickness of all following slurs from 1.2 to 5.0
348 \override Slur #'thickness = #5.0
349 r4 b8 b[( g]) g | g[( e]) e d[( f]) a | a g
351 \addlyrics { The man who feels love's sweet e -- mo -- tion }
355 What if we had needed the Context? What is it? We could
356 guess that slurs are in
357 the Voice context, as they are clearly closely associated
358 with individual lines of music, but can we be sure? To
359 find out, go back to the top of the IR page describing the
360 Slur, where it says @q{Slur objects are created by: Slur
361 engraver}. So slurs will be created in whichever context
362 the @code{Slur_engraver} is in. Follow the link to the
363 @code{Slur_engraver} page. At the very bottom it tells
364 us that @code{Slur_engraver} is part of five Voice contexts,
365 including the standard voice context, @code{Voice}, so our
366 guess was correct. And because @code{Voice} is one of the
367 lowest level contexts we can omit it in this location.
369 @heading Overriding once only
371 @cindex overriding once only
372 @cindex once override
375 As you can see, all the slurs are thicker in the final example
376 above. But, what if we
377 wanted just the first slur to be thicker? This is achieved
378 with the @code{\once} command. Placed immediately before
379 the @code{\override} command it causes it to affect only the
380 slur on the @strong{immediately following} note. If the
381 immediately following note does not have a slur the command
382 has no effect. So the command must be repositioned as follows:
384 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
389 % Increase thickness of immediately following slur only
390 \once \override Slur #'thickness = #5.0
391 b[( g]) g | g[( e]) e d[( f]) a | a g
393 \addlyrics { The man who feels love's sweet e -- mo -- tion }
399 Finally, what if we wanted just the first two slurs to be
400 heavier? Well, we could use two commands, each preceded by
401 @code{\once} placed immediately before each of the notes where
404 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
409 % Increase thickness of immediately following slur only
410 \once \override Slur #'thickness = #5.0
412 % Increase thickness of immediately following slur only
413 \once \override Slur #'thickness = #5.0
414 g[( e]) e d[( f]) a | a g
416 \addlyrics { The man who feels love's sweet e -- mo -- tion }
424 or we could omit the @code{\once} command and use the
425 @code{\revert} command
426 to return the @code{thickness} property to its default value:
428 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
433 % Increase thickness of all following slurs from 1.2 to 5.0
434 \override Slur #'thickness = #5.0
437 % Revert thickness of all following slurs to default of 1.2
438 \revert Slur #'thickness
441 \addlyrics { The man who feels love's sweet e -- mo -- tion }
446 The @code{\revert} command can be used to return any property
447 changed with @code{\override} back to its default value.
448 You may use whichever method best suits what you want to do.
450 That concludes our introduction to the IR, and the basic
451 method of tweaking. Several examples follow in the later
452 sections of this Chapter, but with progressively fewer words
453 of guidance and explanation.
455 @node Properties found in interfaces
456 @subsection Properties found in interfaces
458 @cindex interface properties
459 @cindex properties in interfaces
461 Suppose now that we wish to print the lyrics in italics. What
462 @code{\override} command do we need to do this?
463 We first look in the IR page listing @q{All layout objects}, as
464 before, and look for an object that might print lyrics. We
465 find @code{LyricText}, which looks right. Clicking on this shows
466 the settable properties for lyric text. These include the
467 @code{font-series} and @code{font-size}, but nothing that might
468 give an italic shape.
469 This is because the shape property is one that is common to all
470 font objects, so, rather than including it in every layout
471 object, it is grouped together with other similar common
472 properties and placed in an @strong{Interface}, the
473 @code{font-interface}.
475 So now we need to learn how to find the properties of interfaces,
476 and to discover what objects use these interface properties.
478 Look again at the IR page which describes LyricText. At the
479 bottom of the page is a list of clickable (in the html versions
480 of the IR) interfaces which LyricText supports. The list has
481 seven items, including @code{font-interface}, which looks
482 promising. Clicking on this brings up the properties associated
483 with this interface, which are also properties of all the objects
484 which support it, including LyricText.
486 Now we see all the user-settable properties which control fonts,
487 including @code{font-shape(symbol)}, where @code{symbol} can be
488 set to @code{upright}, @code{italics} or @code{caps}.
490 Let's see if we can now construct the @code{\override} command
491 to change the lyrics to italics. The object is @code{LyricText},
492 the property is @code{'font-shape} and the value is
493 @code{'italic}. As before, we'll omit the context.
495 As an aside, although it is an important one, note that because
497 @code{'font-shape} are symbols they must be introduced with a
498 single apostrophe, @code{'}. That is why apostrophes
499 are needed before @code{'thickness} in the earlier example
500 and @code{'font-shape}. These are both symbols too. So
501 what are symbols? They are special names which are known
502 internally to LilyPond. Some of them are names of properties,
503 like @code{'thickness} or @code{'font-shape}, others are in
504 effect special values that can be given to properties, like
505 @code{'italic}. Note the distinction from arbitary
506 text strings, which would appear as @code{"a text string"}.
508 Ok, so the @code{\override} command we need to print the lyrics
512 \override LyricText #'font-shape = #'italic
516 and this should be placed just in front of and close to the
517 lyrics which it should affect, like this:
529 \override LyricText #'font-shape = #'italic
530 The man who feels love's sweet e -- mo -- tion @}
535 and the lyrics are all printed in italics.
537 (In this case, if you try specifying the context the command
538 will fail. In lyric mode the @code{Lyrics} context is always
539 assumed and must not be specified.)
541 @node Types of properties
542 @subsection Types of properties
544 @cindex Property types
546 So far we have seen two types of property: @code{number} and
547 @code{symbol}. To be valid, the value given to a property
548 must be of the correct type and obey the rules for that type.
549 The type of property is always shown in brackets after the
550 property name in the IR. Here is a list of the types you
551 may need, together with the rules for that type, and some
552 examples. You must add a hash symbol, @code{#}, of course,
553 to the front of these values when they are entered in the
554 @code{\override} command.
556 @multitable @columnfractions .33 .33 .33
557 @headitem Property type
561 @tab Either True or False, represented by #t or #f
563 @item Dimension (in staff space)
564 @tab A positive decimal number (in units of staff space)
567 @tab A valid direction symbol or its numerical equivalent
568 @tab #LEFT, #CENTER, #UP, 1, -1
570 @tab A positive whole number
573 @tab A bracketed set of items separated by spaces,
574 preceded by an apostrophe
575 @tab '(left-edge staff-bar), '(1), '(1.0 0.25 0.5)
577 @tab Any valid markup
578 @tab \markup @{ \italic "cresc." @}
580 @tab A fraction of a whole note constructed with the
582 @tab (ly:make-moment 1 4), (ly:make-moment 3 8)
584 @tab Any positive or negative decimal value
586 @item Pair (of numbers)
587 @tab Two numbers separated by a 'space . space' and enclosed
588 in brackets preceded by an apostrophe
589 @tab '(2 . 3.5), '(0.1 . -3.2)
591 @tab Any of the set of permitted symbols for that property,
592 preceded by an apostrophe
593 @tab 'italic, 'inside
595 @tab A procedure or #f (to cause no action)
596 @tab bend::print, ly:text-interface::print, #f
598 @tab A list of three items enclosed in brackets and preceded
599 by a hash, @code{#}, sign
606 @c Old stuff follows -td
609 @section Common tweaks
615 * Fixing overlapping notation::
616 * Other common tweaks::
617 * Fitting music onto fewer pages::
621 @subsection Moving objects
623 This may come as a surprise, but LilyPond is not perfect. Some notation
624 elements can overlap. This is unfortunate, but (in most cases) is easily
627 TODO: with the new spacing features in 2.12, these specific examples are no
628 longer relevant. However, they still demonstrate powerful features
629 of lilypond, so they remain until somebody creates some better examples.
631 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
632 % temporary code to break this example:
633 \override TextScript #'outside-staff-priority = ##f
634 e4^\markup{ \italic ritenuto } g b e
639 The easiest solution is to increase the distance between the object
640 (in this case text, but it could easily be fingerings or dynamics
641 instead) and the note. In LilyPond, this is called the
642 @code{padding} property; it is measured in staff spaces. For most
643 objects, this value is around 1.0 or less (it varies with each
644 object). We want to increase it, so let's try 1.5
646 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
647 % temporary code to break this example:
648 \override TextScript #'outside-staff-priority = ##f
649 \once \override TextScript #'padding = #1.5
650 e4^\markup{ \italic ritenuto } g b e
653 That looks better, but it isn't quite big enough. After experimenting
654 with a few values, we think 2.3 is the best number in this case. However,
655 this number is merely the result of experimentation and my personal
656 taste in notation. Try the above example with 2.3... but also try higher
657 (and lower) numbers. Which do you think looks the best?
659 The @code{staff-padding} property is closely related. @code{padding}
660 controls the minimum amount of space between an object and the nearest
661 other object (generally the note or the staff lines);
662 @code{staff-padding} controls the minimum amount of space between an
663 object and the staff. This is a subtle difference, but you can see
666 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
667 % temporary code to break this example:
668 \override TextScript #'outside-staff-priority = ##f
670 \once \override TextScript #'padding = #4.6
672 \once \override TextScript #'staff-padding = #4.6
673 c4^"piu mosso" fis a g
675 c'4^"piu mosso" b a b
676 \once \override TextScript #'padding = #4.6
678 \once \override TextScript #'staff-padding = #4.6
679 c4^"piu mosso" fis a g
684 Another solution gives us complete control over placing the object -- we
685 can move it horizontally or vertically. This is done with the
686 @code{extra-offset} property. It is slightly more complicated and can
687 cause other problems. When we move objects with @code{extra-offset},
688 the movement is done after LilyPond has placed all other objects. This
690 that the result can overlap with other objects.
692 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
693 % temporary code to break this example:
694 \override TextScript #'outside-staff-priority = ##f
695 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
696 e4^\markup{ \italic ritenuto } g b e
699 With @code{extra-offset}, the first number controls the horizontal
700 movement (left is negative); the second number controls the vertical
701 movement (up is positive). After a bit of experimenting, we decided
702 that these values look good
704 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
705 % temporary code to break this example:
706 \override TextScript #'outside-staff-priority = ##f
707 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
708 e4^\markup{ \italic ritenuto } g b e
712 Again, these numbers are simply the result of a few experiments and
713 looking at the output. You might prefer the text to be slightly higher,
714 or to the left, or whatever. Try it and look at the result!
716 One final warning: in this section, we used
719 \once \override TextScript @dots{}
722 This tweaks the display of text for the next note. If the note has
723 no text, this tweak does nothing (and does @strong{not} wait until
724 the next bit of text). To change the behavior of everything after
725 the command, omit the @code{\once}. To stop this tweak, use a
726 @code{\revert}. This is explained in depth in
727 @ruser{The \override command}.
729 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
730 % temporary code to break this example:
731 \override TextScript #'outside-staff-priority = ##f
733 \once \override TextScript #'padding = #4.6
736 \once \override TextScript #'padding = #4.6
740 \override TextScript #'padding = #4.6
743 \revert TextScript #'padding
749 This manual: @ruser{The \override command}, @ref{Common tweaks}.
752 @node Fixing overlapping notation
753 @subsection Fixing overlapping notation
755 In @ref{Moving objects}, we saw how to move a @code{TextScript}
756 object. The same mechanism can be used to move other types of
757 objects; simply replace @code{TextScript} with the name of
760 To find the object name, look at the @q{@strong{see also}} at
761 bottom of the relevant documentation page. For example, at
762 the bottom of @ruser{Dynamics}, we see
767 Internals Reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
768 Vertical positioning of these symbols is handled by
769 @internalsref{DynamicLineSpanner}.
773 So to move dynamics around vertically, we use
776 \override DynamicLineSpanner #'padding = #2.0
779 We cannot list every object, but here is a list of the most
782 @multitable @columnfractions .33 .66
783 @headitem Object type @tab Object name
784 @item Dynamics (vertically) @tab @code{DynamicLineSpanner}
785 @item Dynamics (horizontally) @tab @code{DynamicText}
786 @item Ties @tab @code{Tie}
787 @item Slurs @tab @code{Slur}
788 @item Articulations @tab @code{Script}
789 @item Fingerings @tab @code{Fingering}
790 @item Text e.g. @code{^"text"} @tab @code{TextScript}
791 @item Rehearsal / Text marks @tab @code{RehearsalMark}
795 @node Other common tweaks
796 @subsection Other common tweaks
798 Some overrides are so common that predefined commands are provided as
799 short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
800 commands are described in the Notation Reference under the appropriate
803 The complete list of modifications available for each type of
804 object (like slurs or beams) are documented in the Program
805 Reference. However, many layout objects share properties which can be
806 used to apply generic tweaks.
813 The @code{padding} property can be set to increase
814 (or decrease) the distance between symbols that are printed
815 above or below notes. This applies to all objects with
816 @code{side-position-interface}.
818 @lilypond[quote,fragment,relative=1,verbatim]
820 \override Script #'padding = #3
824 @lilypond[quote,fragment,relative=1,verbatim]
825 % This will not work, see below:
826 \override MetronomeMark #'padding = #3
830 \override Score.MetronomeMark #'padding = #3
835 Note in the second example how important it is to figure out what
836 context handles a certain object. Since the @code{MetronomeMark} object
837 is handled in the @code{Score} context, property changes in the
838 @code{Voice} context will not be noticed. For more details, see
839 @ruser{Constructing a tweak}.
844 The @code{extra-offset} property moves objects around
845 in the output; it requires a pair of numbers. The first number
846 controls horizontal movement; a positive number will
847 move the object to the right. The second number controls vertical
848 movement; a positive number will move it higher. The
849 @code{extra-offset} property is a low-level feature: the
850 formatting engine is completely oblivious to these offsets.
852 In the following example, the second fingering is moved a little to
853 the left, and 1.8 staff space downwards:
855 @lilypond[quote,fragment,relative=1,verbatim]
858 \once \override Fingering
859 #'extra-offset = #'(-0.3 . -1.8)
864 Setting the @code{transparent} property will cause an object to be printed
865 in @q{invisible ink}: the object is not printed, but all its other
866 behavior is retained. The object still takes up space, it takes part in
867 collisions, and slurs, ties, and beams can be attached to it.
869 @cindex transparent objects
870 @cindex removing objects
871 @cindex hiding objects
872 @cindex invisible objects
873 The following example demonstrates how to connect different voices
874 using ties. Normally, ties only connect two notes in the same
875 voice. By introducing a tie in a different voice,
877 @lilypond[quote,fragment,relative=2]
886 and blanking the first up-stem in that voice, the tie appears to cross
890 @lilypond[quote,fragment,relative=2,verbatim]
892 \once \override Stem #'transparent = ##t
899 To make sure that the just-blanked stem doesn't squeeze the tie too much,
900 we also lengthen the stem, by setting the @code{length} to
903 @lilypond[quote,fragment,relative=2,verbatim]
905 \once \override Stem #'transparent = ##t
906 \once \override Stem #'length = #8
915 @cindex Tweaks, distances
918 Distances in LilyPond are measured in staff-spaces, while most
919 thickness properties are measured in line-thickness. Some
920 properties are different; for example, the thickness of beams
921 are measured in staff-spaces. For more information, see the
922 relevant portion of the program reference.
925 @node Fitting music onto fewer pages
926 @subsection Fitting music onto fewer pages
928 Sometimes you can end up with one or two staves on a second
929 (or third, or fourth...) page. This is annoying, especially
930 if you look at previous pages and it looks like there is plenty
931 of room left on those.
933 When investigating layout issues, @code{annotate-spacing} is
934 an invaluable tool. This command prints the values of various
935 layout spacing commands; see @ruser{Displaying spacing}, for more
936 details. From the output of @code{annotate-spacing}, we can
937 see which margins we may wish to alter.
939 Other than margins, there are a few other options to save space:
943 You may tell LilyPond to place systems as close together as
944 possible (to fit as many systems as possible onto a page), but
945 then to space those systems out so that there is no blank
946 space at the bottom of the page.
950 between-system-padding = #0.1
951 between-system-space = #0.1
952 ragged-last-bottom = ##f
958 You may force the number of systems (i.e., if LilyPond wants
959 to typeset some music with 11 systems, you could force it to
969 Avoid (or reduce) objects which increase the vertical size of
970 a system. For example, volta repeats (or alternate repeats)
971 require extra space. If these repeats are spread over two
972 systems, they will take up more space than one system with
973 the volta repeats and another system without.
975 Another example is moving dynamics which @q{stick out} of
978 @lilypond[verbatim,quote,fragment]
981 \override DynamicLineSpanner #'padding = #-1.8
982 \override DynamicText #'extra-offset = #'( -2.1 . 0)
988 Alter the horizontal spacing via @code{SpacingSpanner}. See
989 @ruser{Changing horizontal spacing}, for more details.
991 @lilypond[verbatim,quote]
994 g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
995 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
996 d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
997 g4 e e2 | f4 d d2 | c4 e g g | c,1 |
1002 \override SpacingSpanner
1003 #'base-shortest-duration = #(ly:make-moment 1 4)
1012 @node TODO other name
1013 @section TODO other name
1016 * Predefined tweaks::
1017 * Advanced tweaks with Scheme::
1018 * Avoiding tweaks with slower processing::
1019 * The three methods of tweaking::
1022 @node Predefined tweaks
1023 @subsection Predefined tweaks
1025 TODO: Some tweaks are really common, blah blah.
1027 for example \slurUp, \fatText.
1029 Show example, then explain where to find ly/propert-ly.
1032 The Internals Reference documentation contains a lot of information
1033 about LilyPond, but even more information can be gathered from
1034 looking at the internal LilyPond files.
1036 Some default settings (such as the definitions for
1037 @code{\header@{@}}s) are stored as @code{.ly} files. Other
1038 settings (such as the definitions of markup commands) are
1039 stored as @code{.scm} (Scheme) files. Further explanation is
1040 outside the scope of this manual; users should be warned that
1041 a substantial amount of technical knowledge or time is required
1042 to understand these files.
1046 @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
1049 @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
1050 To access this, either @code{cd} into this directory from the
1051 Terminal, or control-click on the LilyPond application and select
1052 @q{Show Package Contents}.
1054 @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
1058 The @file{ly/} and @file{scm/} directories will be of
1059 particular interest. Files such as @file{ly/property-init.ly} and
1060 @file{ly/declarations-init.ly} define all the common tweaks.
1063 @node Advanced tweaks with Scheme
1064 @subsection Advanced tweaks with Scheme
1066 We have seen how LilyPond output can be heavily modified using
1068 @code{\override TextScript #'extra-offset = ( 1 . -1)}. But
1069 we have even more power if we use Scheme. For a full explantion
1070 of this, see the @ref{Scheme tutorial}, and
1071 @ruser{Interfaces for programmers}.
1073 We can use Scheme to simply @code{\override} commands,
1075 @lilypond[quote,verbatim,ragged-right]
1076 padText = #(define-music-function (parser location padding) (number?)
1078 \once \override TextScript #'padding = #$padding
1082 c4^"piu mosso" b a b
1084 c4^"piu mosso" d e f
1086 c4^"piu mosso" fis a g
1090 We can use it to create new commands,
1092 @lilypond[quote,verbatim,ragged-right]
1093 tempoMark = #(define-music-function (parser location padding marktext)
1096 \once \override Score . RehearsalMark #'padding = $padding
1097 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
1098 \mark \markup { \bold $marktext }
1103 \tempoMark #3.0 #"Allegro"
1108 Even music expressions can be passed in.
1110 @lilypond[quote,verbatim,ragged-right]
1111 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
1118 \pattern {d16 dis} { ais16-> b\p }
1123 @node Avoiding tweaks with slower processing
1124 @subsection Avoiding tweaks with slower processing
1126 LilyPond can perform extra checks while it processes files. These
1127 commands will take extra time, but the result may require fewer
1131 %% makes sure text scripts and lyrics are within the paper margins
1132 \override Score.PaperColumn #'keep-inside-line = ##t
1133 \override Score.NonMusicalPaperColumn #'keep-inside-line = ##t
1136 In some cases (see issue 246), this must be done before
1137 @code{\override} commands can be processed.
1141 \override PaperColumn #'keep-inside-line = ##t
1142 \override NonMusicalPaperColumn #'keep-inside-line = ##t
1149 @node The three methods of tweaking
1150 @subsection The three methods of tweaking
1172 FIXME discuss \tweak
1176 FIXME: Move the following words and example into Tweaks or
1177 somewhere more suitable, leaving just a ref here. -td
1179 Ways of correcting horizontal placings are described fully
1180 in the Notation Reference.
1181 We introduce just one here, the @code{force-hshift} property of
1182 @code{NoteColumn}. The lower two notes of the first chord (i.e,
1183 those in the third voice) should not be shifted away from the
1184 note column of the higher two notes. To correct this we set
1185 @code{force-hshift} of these notes to zero.
1186 The lower note of the second chord is best placed just to the
1187 right of the higher notes. We achieve this by setting
1188 @code{force-hshift} of this note to 0.5, ie half a notehead's
1189 width to the right of the note column of the higher notes.
1191 Here's the final result:
1193 @lilypond[quote,verbatim,fragment,ragged-right]
1194 \new Staff \relative c'' {
1197 { c2 aes4. bes8 } \\
1200 \once \override NoteColumn #'force-hshift = #0 <ees c>2
1201 \once \override NoteColumn #'force-hshift = #0.5 des2
1212 - There is a section in the manual on \set vs \override (3.3.7),
1213 which is incomplete. First it doesn't mention \overrideProperty,
1214 nor does it mention properties which are not capitalized at all.
1215 And it should explain that \override should be used to set
1216 properties with hyphenated names, like auto-knee-gap. (I had to
1217 experiment to find out how to do this.)
1220 FIXME: moved from fundamental, dumped here at random.
1222 @lilypond[verbatim,quote,ragged-right]
1223 \new Staff = "main" {
1227 << % Start main and ossia in parallel
1228 { r8 f c c } % Main music
1229 \new Staff \with { % Start ossia staff
1230 \remove "Clef_engraver"
1231 \remove "Time_signature_engraver"
1232 % Reduce size of notes and staff
1234 \override StaffSymbol #'staff-space = #(magstep -2)
1235 alignAboveContext = "main" % Place above main staff
1237 { s8 f f c } % Ossia music
1238 >> % End parallel music