@c -*- coding: utf-8; mode: texinfo; -*- @c This file is part of lilypond-learning.tely @ignore Translation of GIT committish: FILL-IN-HEAD-COMMITTISH When revising a translation, copy the HEAD committish of the version that you are working on. See TRANSLATION for details. @end ignore @node Tweaking output @chapter Tweaking output This chapter discusses how to modify output. LilyPond is extremely configurable; virtually every fragment of output may be changed. NB: This chapter is still under development and this version is somewhat experimental; nothing is fixed. Don't translate yet! @menu * Tweaking basics:: * The Internals Reference manual:: * Common tweaks:: * TODO other name:: @end menu @node Tweaking basics @section Tweaking basics @q{Tweaking} is a LilyPond term for the various methods available to the user for modifying the actions taken during interpretation of the input file and modifying the appearance of the printed output. Some tweaks are very easy to use; others are more complex. But taken together the methods available for tweaking permit almost any desired appearance of the printed music to be achieved. In this section we cover the basic concepts required to understand tweaking. Later we give a variety of potted commands which can simply be copied to obtain the same effect in your own scores, and at the same time we show how these commands may be constructed so that you may learn how to develop your own tweaks. Before starting on this Chapter you may wish to review the section @ref{Contexts and engravers}, as Contexts, Engravers and the Properties contained within them are fundamental to understanding and constructing Tweaks. @menu * Objects and interfaces:: * Naming conventions of objects and properties:: * Tweaking methods:: @end menu @node Objects and interfaces @subsection Objects and interfaces @cindex Objects @cindex Grobs @cindex Spanners @cindex Interfaces Tweaking involves modifying the internal operation and structures of the LilyPond program, so we must first introduce some terms which are used to describe those internal operations and structures. The term @q{Object} is a generic term used to refer to the multitude of internal structures built by LilyPond during the processing of an input file. So when a command like @code{\new Staff} is encountered a new object of type @code{Staff} is constructed. That @code{Staff} object then holds all the properties associated with that particular staff, for example, its name and its key signature, together with details of the engravers which have been assigned to operate within that staff's context. Similarly, there are @code{Voice} objects, @code{Score} objects, @code{Lyric} objects, and objects to represent barlines, noteheads, ties, dynamics, etc, each with their own set of properties. Some types of object are given special names. Objects which represent items of notation on the printed output such as noteheads, stems, slurs, ties, fingering, clefs, etc are called @q{Layout objects}, often known as @q{Graphical Objects}, or @q{Grobs} for short. These are still objects in the generic sense above, and so they too all have properties associated with them, such as their position, size, color, etc. Some layout objects are still more specialised. Phrasing slurs, crescendo hairpins, ottavo marks, and many other grobs are not localised in a single place -- they have a starting point, an ending point, and maybe other properties concerned with their shape. Objects with an extended shape like these are called @q{Spanners}. It remains to explain what @q{Interfaces} are. Many objects, even though they are quite different, share common features which need to be processed in the same way. For example, all grobs have a color, a size, a position, etc, and all these properties are processed in the same way during LilyPond's interpretation of the input file. To simplify these internal operations these common actions and properties are grouped together in an object called a @code{grob-interface}. There are many other groupings of common properties like this, each one given a name ending in @code{-interface}. In total there are over 100 such interfaces. We shall see later why this is of interest and use to the user. These, then, are the main terms relating to objects which we shall use in this chapter. @node Naming conventions of objects and properties @subsection Naming conventions of objects and properties We met some object naming conventions previously, in @ref{Contexts and engravers}. Here for reference is a list of the most common object types together with the conventions for naming them and a couple of examples of some real names. @multitable @columnfractions .33 .33 .33 @headitem Object type @tab Naming convention @tab Example @item Contexts, Layout Objects @tab Aaaa or AaaaAaaaAaaa @tab Staff, GrandStaff, @item Engravers @tab Aaaa_aaa_engraver @tab Clef_engraver, Note_heads_engraver @item Interfaces @tab aaa-aaa-interface @tab grob-interface, break-aligned-interface @item Context Properties @tab aaa or aaaAaaaAaaa @tab alignAboveContext, skipBars @item Layout Object Properties @tab aaa or aaa-aaa-aaa @tab direction, beam-thickness @end multitable As we shall see shortly, the properties of different types of object are modified by different commands, so it is useful to be able to recognise the type of object from the names of its properties. @node Tweaking methods @subsection Tweaking methods We have already met the commands @code{\set} and @code{\with}, used to change the properties of @strong{contexts} and to remove and add engravers, in @ref{Modifying context properties} and @ref{Adding and removing engravers}. We now must meet one more command. The command to change the properties of @strong{layout objects} is @code{\override}. Because this command has to modify internal properties deep within LilyPond its syntax is not as simple as the commands you have met so far. It needs to know precisely which property of which object in which context has to be modified, and what its new value is to be. Let's see how this is done. The general syntax of this command is: @example \override @emph{context}.@emph{layout_object} #'@emph{layout_property} = #@emph{value} @end example @noindent This will set the property with the name @emph{layout_property} of the layout object with the name @emph{layout_object}, which is a member of the @emph{context} context, to the value @emph{value}. For now, don't worry about the @code{#'}, which must precede the layout property, and the @code{#}, which must precede the value. These must always be present in exactly this form. This is the most common command used in tweaking, and most of the rest of this chapter will be directed to presenting examples of how it is used. Once overridden, the property retains its new value until it is overridden again or a @code{\revert} command is encountered. The @code{\revert} command has the following syntax and causes the value of the property to revert to its original default value; note, not its previous value if several @code{\override} commands have been issued. @example \revert @emph{context}.@emph{layout_object} #'@emph{layout_property} @end example There is another form of the override command, @code{\overrideProperty}, which is occasionally required. We mention it here for completeness, but for details see @ruser{Difficult tweaks}. The final tweaking command which is available is @code{\tweak}. It is not really a new command but a shorthand for an @code{\override} command which may be used in a few special circumstances. Again, we shall not discuss or use it here. You may find the details in @ruser{Objects connected to the input}. @node The Internals Reference manual @section The Internals Reference manual @cindex Internals Reference @menu * Properties of layout objects:: * Properties found in interfaces:: @end menu @node Properties of layout objects @subsection Properties of layout objects @cindex properties of layout objects @cindex properties of grobs @cindex grobs, properties of @cindex layout objects, properties of Suppose you have a slur in a score which, to your mind, appears too thin and you'd like to draw it a little thicker. How do you go about doing this? You know from the statements earlier about the flexibility of LilyPond that such a thing should be possible, and you would probably guess that an @code{\override} command would be needed. But is there a thickness property for a slur, and if there is, how might it be modified? This is where the Internals Reference manual comes in. It contains all the information you might need to construct this and all other @code{\override} commands. Before we look at the Internals Reference a word of warning. This is a @strong{reference} document, which means there is little or no explanation contained within it: its purpose is to present information precisely and concisely. This might mean it looks daunting at first sight. Don't worry! The guidance and explanation presented here will enable you to extract the information from the Internals Reference for yourself with just a little practice. @cindex override example @cindex Internals Reference, example of using Let's use a concrete example with a simple fragment of real music: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] { \time 6/8 { r4 b8 b[( g]) g | g[( e]) e d[( f]) a | a g } \addlyrics { The man who feels love's sweet e -- mo -- tion } } @end lilypond Suppose now that we decide we would like the slurs to be a little heavier. Is this possible? The slur is certainly a layout object, so the question is, @q{Is there a property belonging to a slur which controls the heaviness?} To answer this we must look in the Internals Reference, or IR for short. The IR for the version of LilyPond you are using may be found on the LilyPond website at http://lilypond.org. Go to the documentation page and click on the Internals Reference link. For learning purposes you should use the standard html version, not the @q{one big page} or the PDF. For the next few paragraphs to make sense you will need to actually do this as you read. Under the heading @strong{Top} you will see five links. Select the link to the @emph{Backend}, which is where information about layout objects is to be found. There, under the heading @strong{Backend}, select the link to @emph{All layout objects}. The page that appears lists all the layout objects used in your version of LilyPond, in alphabetic order. Select the link to Slur, and the properties of Slurs are listed. (An alternative way of finding this page is from the Notation Reference. On one of the pages that deals with slurs you may find a link to the Internals Reference. This link will take you directly to this page, but often it is easier to go straight to the IR and search there.) This Slur page in the IR tells us first that Slur objects are created by the Slur_engraver. Then it lists the standard settings. Note these are @strong{not} in alphabetic order. Browse down them looking for a property that might control the heaviness of slurs, and you should find @example @code{thickness} (number) @code{1.2} Line thickness, generally measured in @code{line-thickness} @end example This tells us first that there @emph{is} a property that controls thickness, that its value is a simple @emph{number}, that the default value is 1.2, and that the units are in another property called @code{line-thickness}. This looks a good bet to change the heaviness. As we said earlier, there are few to no explanations in the IR, but we already have enough information to try changing the slur thickness. We see that the name of the layout object is @code{Slur}, that the name of the property to change is @code{thickness} and that the new value should be a number somewhat larger than 1.2 if we are to make slurs thicker. But what is the Context? We could guess that slurs are in the Voice context, as they are clearly closely associated with individual lines of music, but can we be sure? To find out, go back to the top of the IR page describing the Slur, where it says @q{Slur objects are created by: Slur engraver}. So slurs will be created in whichever context the @code{Slur_engraver} is in. Follow the link to the @code{Slur_engraver} page. At the very bottom it tells us that @code{Slur_engraver} is part of five Voice contexts, including the standard voice context, @code{Voice}, so our guess was correct. We can now construct the @code{\override} command by simply substituting the values we have found for the names. Let's use a very large value for the thickness at first, so we can be sure the command is working. We get: @example \override Voice.Slur #'thickness = #5.0 @end example Don't forget the @code{#'} preceding the property name and and @code{#} preceding the new value! The final question is, @q{Where should this command be placed?} While you are unsure and learning, the best answer is, @q{Within the music, before the first slur and close to it.} Let's do that: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] { \time 6/8 { % Increase thickness of all following slurs from 1.2 to 5.0 \override Voice.Slur #'thickness = #5.0 r4 b8 b[( g]) g | g[( e]) e d[( f]) a | a g } \addlyrics { The man who feels love's sweet e -- mo -- tion } } @end lilypond @cindex overriding once only @cindex once override @funindex \once As you can see, all the slurs are thicker. But, what if we wanted just the first slur to be thicker? This is achieved with the @code{\once} command. Placed immediately before the @code{\override} command it causes it to affect only the slur on the @strong{immediately following} note. If the immediately following note does not have a slur the command has no effect. So the command must be repositioned as follows: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] { \time 6/8 { r4 b8 % Increase thickness of immediately following slur only \once \override Voice.Slur #'thickness = #5.0 b[( g]) g | g[( e]) e d[( f]) a | a g } \addlyrics { The man who feels love's sweet e -- mo -- tion } } @end lilypond Finally, what if we wanted just the first two slurs to be heavier? Well, we could use two commands, each preceded by @code{\once} placed immediately before each of the notes where the slurs begin: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] { \time 6/8 { r4 b8 % Increase thickness of immediately following slur only \once \override Voice.Slur #'thickness = #5.0 b[( g]) g | % Increase thickness of immediately following slur only \once \override Voice.Slur #'thickness = #5.0 g[( e]) e d[( f]) a | a g } \addlyrics { The man who feels love's sweet e -- mo -- tion } } @end lilypond @cindex revert @funindex \revert @noindent or we could omit the @code{\once} command and use the @code{\revert} command to return the @code{thickness} property to its default value: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] { \time 6/8 { r4 b8 % Increase thickness of all following slurs from 1.2 to 5.0 \override Voice.Slur #'thickness = #5.0 b[( g]) g | g[( e]) % Revert thickness of all following slurs to default of 1.2 \revert Voice.Slur #'thickness e d[( f]) a | a g } \addlyrics { The man who feels love's sweet e -- mo -- tion } } @end lilypond @noindent The @code{\revert} command can be used to return any property changed with @code{\override} back to its default value. You may use whichever method best suits what you want to do. That concludes our introduction to the IR, and the basic method of tweaking. Several examples follow in the later sections of this Chapter, but with progressively fewer words of guidance and explanation. @node Properties found in interfaces @subsection Properties found in interfaces @cindex interface properties @cindex properties in interfaces Suppose now that we wish to color a slur red. We would go to the properties on Slurs in the IR as described in the previous section, and look in vain, because there is nothing there that looks like it might change the color. This is because the color property is one that is common to all layout objects, so, rather than including it in every layout object, it is grouped together with other similar common properties and placed in an @strong{Interface}, the @code{grob-interface}. (Remember, grob is short for @q{graphical object}, itself another name for a layout object.) So now we need to learn how to find the properties of interfaces, and to discover what objects use these interface properties. Look again at the IR page which describes the Slur. At the bottom of the page is a list of clickable (in the html versions of the IT) interfaces which the Slur supports. The list has three items: @code{spanner-interface}, @code{slur-interface} and @code{grob-interface}. The @code{spanner-interface} holds properties common to spanners -- objects which extend over several notes -- as do Slurs. The @code{slur-interface} holds properties common to ordinary slurs and phrasing slurs. The @code{grob-interface} holds properties common to all layout objects, and it is here that you will find the @code{color} property, which appears as @example color(list) The color of this grob @end example ... to be continued @ignore @c The rest of this section is rubbish and will need to be rewritten -td The value then is described as a @emph{list}? Why do we need a list to specify a color? Well, we don't, but there are several ways to specify a color and some of them do need a list. See the Notation Reference @ruser{List of colors}. This shows the @q{Normal colors} and the longer list of @q{X color names}. The normal colors are written as a one-member list, which can be written simply as @code{red}. But the X color names must be written as a two-member list: @example (x11-color 'LimeGreen) @end example @noindent where the first item in the list is always @q{x11-color} to indicate this is a color from the longer list of X11 colors, and the second item is the name of the color from the list of X11 colors in the Notation Reference. @cindex properties as lists @cindex properties as text strings This introduces two new concepts. First the brackets round this property value are required to form the two items into a list, as required by the color property. Brackets would generate an error if placed around a @q{normal color}, though, because these are shorthand names known to LilyPond which generate the appropriate list automatically. Second, because the second item is a text string it needs to be introduced with a single apostrophe, @code{'}. This is why these apostrophes are needed before @code{'thickness} and @code{'color'}. These are both text strings too. So, putting this into practice, we can change the second slur to the normal color magenta and the third slur to the X11 color, DarkOrange, where we have made all the slurs thicker to show the colors better, as follows: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] { \time 6/8 { \override Voice.Slur #'thickness = #5.0 r4 b8 b[( g]) g | \once \override Voice.Slur #'color = #magenta g[( e]) e \once \override Voice.Slur #'color = #(x11-color 'DarkOrange) d[( f]) a | a g } \addlyrics { The man who feels love's sweet e -- mo -- tion } } @end lilypond @end ignore @c Old stuff follows -td @node Common tweaks @section Common tweaks blah blah @menu * Moving objects:: * Fixing overlapping notation:: * Other common tweaks:: * Fitting music onto fewer pages:: @end menu @node Moving objects @subsection Moving objects This may come as a surprise, but LilyPond is not perfect. Some notation elements can overlap. This is unfortunate, but (in most cases) is easily solved. TODO: with the new spacing features in 2.12, these specific examples are no longer relevant. However, they still demonstrate powerful features of lilypond, so they remain until somebody creates some better examples. @lilypond[quote,fragment,ragged-right,verbatim,relative=2] % temporary code to break this example: \override TextScript #'outside-staff-priority = ##f 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] % temporary code to break this example: \override TextScript #'outside-staff-priority = ##f \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] % temporary code to break this example: \override TextScript #'outside-staff-priority = ##f c4^"piu mosso" b a b \once \override TextScript #'padding = #4.6 c4^"piu mosso" d e f \once \override TextScript #'staff-padding = #4.6 c4^"piu mosso" fis a g \break c'4^"piu mosso" b a b \once \override TextScript #'padding = #4.6 c4^"piu mosso" d e f \once \override TextScript #'staff-padding = #4.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] % temporary code to break this example: \override TextScript #'outside-staff-priority = ##f \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] % temporary code to break this example: \override TextScript #'outside-staff-priority = ##f \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). To change the behavior of everything after the command, omit the @code{\once}. To stop this tweak, use a @code{\revert}. This is explained in depth in @ruser{The \override command}. @lilypond[quote,fragment,ragged-right,verbatim,relative=3] % temporary code to break this example: \override TextScript #'outside-staff-priority = ##f c4^"piu mosso" b \once \override TextScript #'padding = #4.6 a4 b c4^"piu mosso" d e f \once \override TextScript #'padding = #4.6 c4^"piu mosso" d e f c4^"piu mosso" d e f \break \override TextScript #'padding = #4.6 c4^"piu mosso" d e f c4^"piu mosso" d e f \revert TextScript #'padding c4^"piu mosso" d e f @end lilypond @seealso This manual: @ruser{The \override command}, @ref{Common tweaks}. @node Fixing overlapping notation @subsection Fixing overlapping notation In @ref{Moving objects}, we saw how to move a @code{TextScript} object. The same mechanism can be used to move other types of objects; simply replace @code{TextScript} with the name of another object. To find the object name, look at the @q{@strong{see also}} at bottom of the relevant documentation page. For example, at the bottom of @ruser{Dynamics}, we see @quotation @seealso Internals Reference: @internalsref{DynamicText}, @internalsref{Hairpin}. Vertical positioning of these symbols is handled by @internalsref{DynamicLineSpanner}. @end quotation @noindent So to move dynamics around vertically, we use @example \override DynamicLineSpanner #'padding = #2.0 @end example We cannot list every object, but here is a list of the most common objects. @multitable @columnfractions .33 .66 @headitem Object type @tab Object name @item Dynamics (vertically) @tab @code{DynamicLineSpanner} @item Dynamics (horizontally) @tab @code{DynamicText} @item Ties @tab @code{Tie} @item Slurs @tab @code{Slur} @item Articulations @tab @code{Script} @item Fingerings @tab @code{Fingering} @item Text e.g. @code{^"text"} @tab @code{TextScript} @item Rehearsal / Text marks @tab @code{RehearsalMark} @end multitable @node Other common tweaks @subsection Other common tweaks Some overrides are so common that predefined commands are provided as short-cuts, such as @code{\slurUp} and @code{\stemDown}. These commands are described in the Notation Reference under the appropriate sections. The complete list of modifications available for each type of object (like slurs or beams) are documented in the Program Reference. However, many layout objects share properties which can be used to apply generic tweaks. @itemize @cindex padding @item The @code{padding} property can be set to increase (or decrease) the distance between symbols that are printed above or below notes. This applies to all objects with @code{side-position-interface}. @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 @code{Score} context, property changes in the @code{Voice} context will not be noticed. For more details, see @ruser{Constructing a tweak}. @cindex extra-offset @item The @code{extra-offset} property moves objects around in the output; it requires a pair of numbers. The first number controls horizontal movement; a positive number will move the object to the right. The second number controls vertical movement; a positive number will move it higher. 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: @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 @q{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 To make sure that the just-blanked stem doesn't squeeze the tie too much, we also lengthen the stem, by setting the @code{length} to @code{8}, @lilypond[quote,fragment,relative=2,verbatim] << { \once \override Stem #'transparent = ##t \once \override Stem #'length = #8 b8~ b8\noBeam } \\ { b[ g8] } >> @end lilypond @end itemize @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 are measured in staff-spaces. For more information, see the relevant portion of the program reference. @node Fitting music onto fewer pages @subsection Fitting music onto fewer pages Sometimes you can end up with one or two staves on a second (or third, or fourth...) page. This is annoying, especially if you look at previous pages and it looks like there is plenty of room left on those. When investigating layout issues, @code{annotate-spacing} is an invaluable tool. This command prints the values of various layout spacing commands; see @ruser{Displaying spacing}, for more details. From the output of @code{annotate-spacing}, we can see which margins we may wish to alter. Other than margins, there are a few other options to save space: @itemize @item You may tell LilyPond to place systems as close together as possible (to fit as many systems as possible onto a page), but then to space those systems out so that there is no blank space at the bottom of the page. @example \paper @{ between-system-padding = #0.1 between-system-space = #0.1 ragged-last-bottom = ##f ragged-bottom = ##f @} @end example @item You may force the number of systems (i.e., if LilyPond wants to typeset some music with 11 systems, you could force it to use 10). @example \paper @{ system-count = #10 @} @end example @item Avoid (or reduce) objects which increase the vertical size of a system. For example, volta repeats (or alternate repeats) require extra space. If these repeats are spread over two systems, they will take up more space than one system with the volta repeats and another system without. Another example is moving dynamics which @q{stick out} of a system. @lilypond[verbatim,quote,fragment] \relative c' { e4 c g\f c \override DynamicLineSpanner #'padding = #-1.8 \override DynamicText #'extra-offset = #'( -2.1 . 0) e4 c g\f c } @end lilypond @item Alter the horizontal spacing via @code{SpacingSpanner}. See @ruser{Changing horizontal spacing}, for more details. @lilypond[verbatim,quote] \score { \relative c'' { g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 | g4 e e2 | f4 d d2 | c4 e g g | c,1 | d4 d d d | d4 e f2 | e4 e e e | e4 f g2 | g4 e e2 | f4 d d2 | c4 e g g | c,1 | } \layout { \context { \Score \override SpacingSpanner #'base-shortest-duration = #(ly:make-moment 1 4) } } } @end lilypond @end itemize @node TODO other name @section TODO other name @menu * Predefined tweaks:: * Advanced tweaks with Scheme:: * Avoiding tweaks with slower processing:: * The three methods of tweaking:: @end menu @node Predefined tweaks @subsection Predefined tweaks TODO: Some tweaks are really common, blah blah. for example \slurUp, \fatText. Show example, then explain where to find ly/propert-ly. The Internals Reference documentation contains a lot of information about LilyPond, but even more information can be gathered from looking at the internal LilyPond files. Some default settings (such as the definitions for @code{\header@{@}}s) are stored as @code{.ly} files. Other settings (such as the definitions of markup commands) are stored as @code{.scm} (Scheme) files. Further explanation is outside the scope of this manual; users should be warned that a substantial amount of technical knowledge or time is required to understand these files. @itemize @item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/} @item OSX: @file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}. To access this, either @code{cd} into this directory from the Terminal, or control-click on the LilyPond application and select @q{Show Package Contents}. @item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/} @end itemize The @file{ly/} and @file{scm/} directories will be of particular interest. Files such as @file{ly/property-init.ly} and @file{ly/declarations-init.ly} define all the common tweaks. @node Advanced tweaks with Scheme @subsection 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. For a full explantion of this, see the @ref{Scheme tutorial}, and @ruser{Interfaces for programmers}. We can use Scheme to simply @code{\override} commands, @lilypond[quote,verbatim,ragged-right] padText = #(define-music-function (parser location padding) (number?) #{ \once \override TextScript #'padding = #$padding #}) \relative c''' { c4^"piu mosso" b a b \padText #1.8 c4^"piu mosso" d e f \padText #2.6 c4^"piu mosso" fis a g } @end lilypond We can use it to create new commands, @lilypond[quote,verbatim,ragged-right] tempoMark = #(define-music-function (parser location padding marktext) (number? string?) #{ \once \override Score . RehearsalMark #'padding = $padding \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0) \mark \markup { \bold $marktext } #}) \relative c'' { c2 e \tempoMark #3.0 #"Allegro" g c } @end lilypond Even music expressions can be passed in. @lilypond[quote,verbatim,ragged-right] pattern = #(define-music-function (parser location x y) (ly:music? ly:music?) #{ $x e8 a b $y b a e #}) \relative c''{ \pattern c8 c8\f \pattern {d16 dis} { ais16-> b\p } } @end lilypond @node Avoiding tweaks with slower processing @subsection Avoiding tweaks with slower processing LilyPond can perform extra checks while it processes files. These commands will take extra time, but the result may require fewer manual tweaks. @example %% makes sure text scripts and lyrics are within the paper margins \override Score.PaperColumn #'keep-inside-line = ##t \override Score.NonMusicalPaperColumn #'keep-inside-line = ##t @end example In some cases (see issue 246), this must be done before @code{\override} commands can be processed. @verbatim \new Score \with { \override PaperColumn #'keep-inside-line = ##t \override NonMusicalPaperColumn #'keep-inside-line = ##t } { .. } @end verbatim @node The three methods of tweaking @subsection The three methods of tweaking FIXME write this. @verbatim \override @end verbatim @verbatim \with { } @end verbatim @verbatim \layout{ \context }} @end verbatim FIXME discuss \tweak FIXME: Move the following words and example into Tweaks or somewhere more suitable, leaving just a ref here. -td Ways of correcting horizontal placings are described fully in the Notation Reference. We introduce just one here, the @code{force-hshift} property of @code{NoteColumn}. The lower two notes of the first chord (i.e, those in the third voice) should not be shifted away from the note column of the higher two notes. To correct this we set @code{force-hshift} of these notes to zero. The lower note of the second chord is best placed just to the right of the higher notes. We achieve this by setting @code{force-hshift} of this note to 0.5, ie half a notehead's width to the right of the note column of the higher notes. Here's the final result: @lilypond[quote,verbatim,fragment,ragged-right] \new Staff \relative c'' { \key aes \major << { c2 aes4. bes8 } \\ { aes2 f4 fes } \\ { \voiceFour \once \override NoteColumn #'force-hshift = #0 2 \once \override NoteColumn #'force-hshift = #0.5 des2 } >> | 1 | } @end lilypond FIXME: - There is a section in the manual on \set vs \override (3.3.7), which is incomplete. First it doesn't mention \overrideProperty, nor does it mention properties which are not capitalized at all. And it should explain that \override should be used to set properties with hyphenated names, like auto-knee-gap. (I had to experiment to find out how to do this.) FIXME: moved from fundamental, dumped here at random. @lilypond[verbatim,quote,ragged-right] \new Staff = "main" { \relative g' { r4 g8 g c4 c8 d | e4 << % Start main and ossia in parallel { r8 f c c } % Main music \new Staff \with { % Start ossia staff \remove "Clef_engraver" \remove "Time_signature_engraver" % Reduce size of notes and staff fontSize = #-2 \override StaffSymbol #'staff-space = #(magstep -2) alignAboveContext = "main" % Place above main staff } { s8 f f c } % Ossia music >> % End parallel music r4 | } } @end lilypond