X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftweaks.itely;fp=Documentation%2Fuser%2Ftweaks.itely;h=0000000000000000000000000000000000000000;hb=69f0ec479a6ade46d0a227755bb02562112c6743;hp=304fe5aa75dd4f5424f9d3347e0f5adb1f09881f;hpb=1423508c355989fa26a8cfe5985b0d6e1ab0a538;p=lilypond.git diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely deleted file mode 100644 index 304fe5aa75..0000000000 --- a/Documentation/user/tweaks.itely +++ /dev/null @@ -1,3769 +0,0 @@ -@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 - -@c \version "2.12.0" - -@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. - - -@menu -* Tweaking basics:: -* The Internals Reference manual:: -* Appearance of objects:: -* Placement of objects:: -* Collisions of objects:: -* Further tweaking:: -@end menu - -@node Tweaking basics -@section Tweaking basics - -@menu -* Introduction to tweaks:: -* Objects and interfaces:: -* Naming conventions of objects and properties:: -* Tweaking methods:: -@end menu - -@node Introduction to tweaks -@subsection Introduction to tweaks - -@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 ready-made 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. - -@node Objects and interfaces -@subsection Objects and interfaces - -@cindex object -@cindex grob -@cindex spanner -@cindex interface -@cindex properties, object -@cindex object properties -@cindex layout object -@cindex object, layout -@cindex interface - -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 objects to hold the properties of all other -contexts, such as @code{Voice} objects, @code{Score} objects, -@code{Lyrics} objects, as well as objects to represent all -notational elements such as bar lines, -note heads, ties, dynamics, etc. Every object has its own set of -property values. - -Some types of object are given special names. Objects which represent -items of notation on the printed output such as note heads, 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 specialized. Phrasing slurs, -crescendo hairpins, ottava marks, and many other grobs are not -localized 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 - -@cindex naming conventions for objects -@cindex naming conventions for properties -@cindex objects, naming conventions -@cindex properties, naming conventions - -We met some object naming conventions previously, in -@ref{Contexts and engravers}. Here for reference is a list -of the most common object and property types together with -the conventions for naming them and a couple of examples of -some real names. We have used @q{A} to stand for any capitalized -alphabetic character and @q{aaa} to stand for any number of -lower-case alphabetic characters. Other characters are used -verbatim. - -@multitable @columnfractions .33 .33 .33 -@headitem Object/property type - @tab Naming convention - @tab Examples -@item Contexts - @tab Aaaa or AaaaAaaaAaaa - @tab Staff, GrandStaff -@item Layout Objects - @tab Aaaa or AaaaAaaaAaaa - @tab Slur, NoteHead -@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 recognize the type of object from the names of its -properties. - - -@node Tweaking methods -@subsection Tweaking methods - -@cindex tweaking methods - -@strong{\override command} - -@cindex override command -@cindex override syntax - -@funindex \override -@funindex override - -We have already met the commands @code{\set} and @code{\with}, used to -change the properties of @strong{contexts} and to remove and add -@strong{engravers}, in @ref{Modifying context properties}, and -@ref{Adding and removing engravers}. We must now introduce some more -important commands. - -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 used 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 @var{Context}.@var{LayoutObject} #'@var{layout-property} = -#@var{value} -@end example - -@noindent -This will set the property with the name @var{layout-property} of the -layout object with the name @var{LayoutObject}, which is a member of -the @var{Context} context, to the value @var{value}. - -The @var{Context} can be omitted (and usually is) when the -required context is unambiguously implied and is one of lowest -level contexts, i.e., @code{Voice}, @code{ChordNames} or -@code{Lyrics}, and we shall omit it in many of the following -examples. We shall see later when it must be specified. - -Later sections deal comprehensively with properties and their -values, but to illustrate the format and use of these commands -we shall use just a few simple properties and values which are -easily understood. - -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. Here is a simple example to change the color of the -note head: - -@cindex color property, example -@cindex NoteHead, example of overriding - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] -c d -\override NoteHead #'color = #red -e f g -\override NoteHead #'color = #green -a b c -@end lilypond - -@strong{\revert command} - -@cindex revert command - -@funindex \revert -@funindex revert - -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 @var{Context}.@var{LayoutObject} #'@var{layout-property} -@end example - -Again, just like @var{Context} in the @code{\override} command, -@var{Context} is often not needed. It will be omitted -in many of the following examples. Here we revert the color -of the note head to the default value for the final two notes: - -@cindex color property, example -@cindex NoteHead, example of overriding - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] -c d -\override NoteHead #'color = #red -e f g -\override NoteHead #'color = #green -a -\revert NoteHead #'color -b c -@end lilypond - -@strong{\once prefix} - -@funindex \once -@funindex once - -Both the @code{\override} and the @code{\set} commands may be -prefixed by @code{\once}. This causes the following -@code{\override} or @code{\set} command to be effective only -during the current musical moment before the property reverts -back to its default value. Using the same example, we can -change the color of a single note like this: - -@cindex color property, example -@cindex NoteHead, example of overriding - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] -c d -\once \override NoteHead #'color = #red -e f g -\once \override NoteHead #'color = #green -a b c -@end lilypond - -@strong{\overrideProperty command} - -@cindex overrideProperty command - -@funindex \overrideProperty -@funindex overrideProperty - -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}. -@c Maybe explain in a later iteration -td - -@strong{\tweak command} - -@cindex tweak command - -@funindex \tweak -@funindex tweak - -The final tweaking command which is available is @code{\tweak}. -This should be used to change the properties of objects which -occur at the same musical moment, such as the notes within a -chord. Using @code{\override} would affect all the notes -within a chord, whereas @code{\tweak} affects just the following -item in the input stream. - -Here's an example. Suppose we wish to change the size of the -middle note head (the E) in a C major chord. Let's first see what -@code{\once \override} would do: - -@cindex font-size property, example -@cindex NoteHead, example of overriding - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] - 4 - \once \override NoteHead #'font-size = #-3 - - -@end lilypond - -We see the override affects @emph{all} the note heads in the chord. -This is because all the notes of a chord occur at the same -@emph{musical moment}, and the action of @code{\once} is to -apply the override to all layout objects of the type specified -which occur at the same musical moment as the @code{\override} -command itself. - -The @code{\tweak} command operates in a different way. It acts -on the immediately following item in the input stream. However, -it is effective only on objects which are created directly from -the input stream, essentially note heads and articulations; -objects such as stems and accidentals are created later and -cannot be tweaked in this way. Furthermore, when it is applied -to note heads these @emph{must} be within a chord, i.e., within -single angle brackets, so to tweak a single note the @code{\tweak} -command must be placed inside single angle brackets with the -note. - -So to return to our example, the size of the middle note of -a chord would be changed in this way: - -@cindex font-size property, example -@cindex @code{\tweak}, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] - 4 - 4 -@end lilypond - -Note that the syntax of @code{\tweak} is different from that -of the @code{\override} command. Neither the context nor the -layout object should be specified; in fact, it would generate -an error to do so. These are both implied by the following -item in the input stream. Note also that an equals sign should -not be present. So the general syntax of the -@code{\tweak} command is simply - -@example -\tweak #'@var{layout-property} #@var{value} -@end example - -A @code{\tweak} command can also be used to modify just one in -a series of articulations, as shown here: - -@cindex color property, example -@cindex @code{\tweak}, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -a ^Black - -\tweak #'color #red ^Red - -\tweak #'color #green _Green -@end lilypond - -@noindent -Note that the @code{\tweak} command must be preceded by an -articulation mark as if it were an articulation itself. - -@cindex tuplets, nested -@cindex triplets, nested -@cindex bracket, tuplet -@cindex bracket, triplet -@cindex tuplet bracket -@cindex triplet bracket - -@funindex TupletBracket - -The @code{\tweak} command must also be used to change the -appearance of one of a set of nested tuplets which begin at the -same musical moment. In the following example, the long tuplet -bracket and the first of the three short brackets begin at the -same musical moment, so any @code{\override} command would apply -to both of them. In the example, @code{\tweak} is used to -distinguish between them. The first @code{\tweak} command -specifies that the long tuplet bracket is to be placed above the -notes and the second one specifies that the tuplet number is to be -printed in red on the first short tuplet bracket. - -@cindex @code{\tweak}, example -@cindex direction property, example -@cindex color property, example - -@lilypond[quote,ragged-right,verbatim,fragment,relative=2] -\tweak #'direction #up -\times 4/3 { - \tweak #'color #red - \times 2/3 { c8[ c8 c8] } - \times 2/3 { c8[ c8 c8] } - \times 2/3 { c8[ c8 c8] } -} -@end lilypond - -If nested tuplets do not begin at the same moment, their -appearance may be modified in the usual way with -@code{\override} commands: - -@cindex text property, example -@cindex tuplet-number function, example -@cindex transparent property, example -@cindex TupletNumber, example of overriding - -@c NOTE Tuplet brackets collide if notes are high on staff -@c See issue 509 -@lilypond[quote,ragged-right,verbatim,fragment,relative=1] -\times 2/3 { c8[ c c]} -\once \override TupletNumber - #'text = #tuplet-number::calc-fraction-text -\times 2/3 { - c[ c] - c[ c] - \once \override TupletNumber #'transparent = ##t - \times 2/3 { c8[ c c] } -\times 2/3 { c8[ c c]} -} -@end lilypond - - -@seealso -Notation Reference: -@ruser{The tweak command}. - - -@node The Internals Reference manual -@section The Internals Reference manual - -@cindex Internals Reference - -@menu -* Properties of layout objects:: -* Properties found in interfaces:: -* Types of properties:: -@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 -@cindex Internals Reference manual - -Suppose you have a slur in a score which, to your mind, -appears too thin and you'd like to draw it a little heavier. -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 -heaviness 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 -means it might look 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 -@cindex @code{\addlyrics} example - -Let's use a concrete example with a simple fragment of real -music: - -@lilypond[quote,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 @uref{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 if you have an idea about the name of the layout object -to be tweaked, 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 looks a good bet to change the heaviness. It tells us that -the value of @code{thickness} is a simple @emph{number}, -that the default value is 1.2, and that the units are -in another property called @code{line-thickness}. - -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. - -We can now construct the @code{\override} command by simply -substituting the values we have found for the names, omitting -the context. 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 Slur #'thickness = #5.0 -@end example - -Don't forget the @code{#'} preceding the -property name and a @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: - -@cindex Slur example of overriding -@cindex thickness property, example - -@lilypond[quote,verbatim,relative=2] -{ - \time 6/8 - { - % Increase thickness of all following slurs from 1.2 to 5.0 - \override 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 - -@noindent -and we see that the slur is indeed heavier. - -So this is the basic way of constructing @code{\override} -commands. There are a few more complications that we -shall meet in later sections, but you now know all the -essentials required to make up your own -- but you will -still need some practice. This is provided in the examples -which follow. - -@subheading Finding the context - -@cindex context, finding -@cindex context, identifying correct - -But first, what if we had needed to specify the Context? -What should it be? 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. And because @code{Voice} is one of the -lowest level contexts which is implied unambiguously by -the fact that we are entering notes, we can omit it in this -location. - -@subheading Overriding once only - -@cindex overriding once only -@cindex once override - -@funindex \once -@funindex once - -As you can see, @emph{all} the slurs are thicker in the final example -above. 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 change only the slur -which begins on the @strong{immediately following} note. If the -immediately following note does not begin a slur the command has no -effect at all -- it is not remembered until a slur is encountered, it -is simply discarded. So the command with @code{\once} must be -repositioned as follows: - -@cindex Slur, example of overriding -@cindex thickness property, example - -@lilypond[quote,verbatim,relative=2] -{ - \time 6/8 - { - r4 b8 - % Increase thickness of immediately following slur only - \once \override 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 - -@noindent -Now only the first slur is made heavier. - -The @code{\once} command can also be used before the @code{\set} -command. - -@subheading Reverting - -@cindex revert -@cindex default properties, reverting to - -@funindex \revert -@funindex revert - -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: - -@cindex Slur, example of overriding -@cindex thickness property, example - -@lilypond[quote,verbatim,relative=2] -{ - \time 6/8 - { - r4 b8 - % Increase thickness of immediately following slur only - \once \override Slur #'thickness = #5.0 - b[( g]) g | - % Increase thickness of immediately following slur only - \once \override 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 - -@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 -after the second slur: - -@cindex Slur, example of overriding -@cindex thickness property, example - -@lilypond[quote,verbatim,relative=2] -{ - \time 6/8 - { - r4 b8 - % Increase thickness of all following slurs from 1.2 to 5.0 - \override Slur #'thickness = #5.0 - b[( g]) g | - g[( e]) - % Revert thickness of all following slurs to default of 1.2 - \revert 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, partly to introduce you to some of the -additional features of the IR, and partly to give you more -practice in extracting information from it. These examples will -contain progressively fewer words of guidance and explanation. - - -@node Properties found in interfaces -@subsection Properties found in interfaces - -@cindex interface -@cindex interface properties -@cindex properties in interfaces - -Suppose now that we wish to print the lyrics in italics. What form of -@code{\override} command do we need to do this? We first look in the -IR page listing @q{All layout objects}, as before, and look for an -object that might control lyrics. We find @code{LyricText}, which -looks right. Clicking on this shows the settable properties for lyric -text. These include the @code{font-series} and @code{font-size}, but -nothing that might give an italic shape. This is because the shape -property is one that is common to all font 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{font-interface}. - -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 LyricText. At the bottom of -the page is a list of clickable interfaces which LyricText supports. -The list has several items, including @code{font-interface}. Clicking -on this brings up the properties associated with this interface, which -are also properties of all the objects which support it, including -LyricText. - -Now we see all the user-settable properties which control fonts, -including @code{font-shape(symbol)}, where @code{symbol} can be -set to @code{upright}, @code{italics} or @code{caps}. - -You will notice that @code{font-series} and @code{font-size} are also -listed there. This immediately raises the question: Why are the -common font properties @code{font-series} and @code{font-size} listed -under @code{LyricText} as well as under the interface -@code{font-interface} but @code{font-shape} is not? The answer is -that @code{font-series} and @code{font-size} are changed from their -global default values when a @code{LyricText} object is created, but -@code{font-shape} is not. The entries in @code{LyricText} then tell -you the values for those two properties which apply to -@code{LyricText}. Other objects which support @code{font-interface} -will set these properties differently when they are created. - -Let's see if we can now construct the @code{\override} command -to change the lyrics to italics. The object is @code{LyricText}, -the property is @code{font-shape} and the value is -@code{italic}. As before, we'll omit the context. - -As an aside, although it is an important one, note that because the -values of @code{font-shape} are symbols they must be introduced with a -single apostrophe, @code{'}. That is why apostrophes are needed -before @code{thickness} in the earlier example and @code{font-shape}. -These are both symbols too. Symbols are then read internally by -LilyPond. Some of them are the names of properties, like -@code{thickness} or @code{font-shape}, others are used as values that -can be given to properties, like @code{italic}. Note the distinction -from arbitrary text strings, which would appear as @code{"a text -string"}; for more details about symbols and strings, see @ref{Scheme -tutorial}. - -So we see that the @code{\override} command needed to print the lyrics -in italics is: - -@example -\override LyricText #'font-shape = #'italic -@end example - -@noindent -This should be placed just in front of the lyrics we wish to affect, -like so: - -@cindex font-shape property, example -@cindex italic, example -@cindex LyricText, example of overriding -@cindex @code{\addlyrics}, example - -@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 { - \override LyricText #'font-shape = #'italic - The man who feels love's sweet e -- mo -- tion - } -} -@end lilypond - -@noindent -and the lyrics are all printed in italics. - -@subheading Specifying the context in lyric mode - -@cindex context, specifying in lyric mode -@cindex lyric mode, specifying context - -In the case of lyrics, if you try specifying the context in the -format given earlier the command will fail. A syllable -entered in lyricmode is terminated by either a space, -a newline or a digit. All other characters are included -as part of the syllable. For this reason a space or newline -must appear before the terminating @code{@}} to prevent it being -included as part of the final syllable. Similarly, -spaces must be inserted before and after the -period or dot, @q{.}, separating the context name from the -object name, as otherwise the two names are run together and -the interpreter cannot recognize them. So the command should be: - -@example -\override Lyrics . LyricText #'font-shape = #'italic -@end example - -@warning{In lyrics always leave whitespace between the final -syllable and the terminating brace.} - -@warning{In overrides in lyrics always place spaces around -the dot between the context name and the object name.} - - -@seealso -Learning Manual: @ref{Scheme tutorial}. - - -@node Types of properties -@subsection Types of properties - -@cindex property types - -So far we have seen two types of property: @code{number} and -@code{symbol}. To be valid, the value given to a property -must be of the correct type and obey the rules for that type. -The type of property is always shown in brackets after the -property name in the IR. Here is a list of the types you may -need, together with the rules for that type, and some examples. -You must always add a hash symbol, @code{#}, of course, -to the front of these values when they are entered in the -@code{\override} command. - -@multitable @columnfractions .2 .45 .35 -@headitem Property type - @tab Rules - @tab Examples -@item Boolean - @tab Either True or False, represented by #t or #f - @tab @code{#t}, @code{#f} -@item Dimension (in staff space) - @tab A positive decimal number (in units of staff space) - @tab @code{2.5}, @code{0.34} -@item Direction - @tab A valid direction constant or its numerical equivalent (decimal -values between -1 and 1 are allowed) - @tab @code{LEFT}, @code{CENTER}, @code{UP}, - @code{1}, @code{-1} -@item Integer - @tab A positive whole number - @tab @code{3}, @code{1} -@item List - @tab A set of values separated by spaces, enclosed in parentheses -and preceded by an apostrophe - @tab @code{'(left-edge staff-bar)}, @code{'(1)}, - @code{'(1.0 0.25 0.5)} -@item Markup - @tab Any valid markup - @tab @code{\markup @{ \italic "cresc." @}} -@item Moment - @tab A fraction of a whole note constructed with the -make-moment function - @tab @code{(ly:make-moment 1 4)}, - @code{(ly:make-moment 3 8)} -@item Number - @tab Any positive or negative decimal value - @tab @code{3.5}, @code{-2.45} -@item Pair (of numbers) - @tab Two numbers separated by a @q{space . space} and enclosed -in brackets preceded by an apostrophe - @tab @code{'(2 . 3.5)}, @code{'(0.1 . -3.2)} -@item Symbol - @tab Any of the set of permitted symbols for that property, -preceded by an apostrophe - @tab @code{'italic}, @code{'inside} -@item Unknown - @tab A procedure, or @code{#f} to cause no action - @tab @code{bend::print}, @code{ly:text-interface::print}, - @code{#f} -@item Vector - @tab A list of three items enclosed in parentheses and preceded -by apostrophe-hash, @code{'#}. - @tab @code{'#(#t #t #f)} -@end multitable - - -@seealso -Learning Manual: @ref{Scheme tutorial}. - - -@node Appearance of objects -@section Appearance of objects - -Let us now put what we have learned into practice with a few -examples which show how tweaks may be used to change the -appearance of the printed music. - -@menu -* Visibility and color of objects:: -* Size of objects:: -* Length and thickness of objects:: -@end menu - -@node Visibility and color of objects -@subsection Visibility and color of objects - -In the educational use of music we might wish to print a score -with certain elements omitted as an exercise for the student, -who is required to supply them. As a simple example, -let us suppose the exercise is to supply the missing bar lines -in a piece of music. But the bar lines are normally inserted -automatically. How do we prevent them printing? - -Before we tackle this, let us remember that object properties are -grouped in what are called @emph{interfaces} -- see @ref{Properties -found in interfaces}. This is simply to group together those -properties that may be used together to tweak a graphical object -- if -one of them is allowed for an object, so are the others. Some objects -then use the properties in some interfaces, others use them from other -interfaces. The interfaces which contain the properties used by a -particular grob are listed in the IR at the bottom of the page -describing that grob, and those properties may be viewed by looking at -those interfaces. - -We explained how to find information about grobs in @ref{Properties of -layout objects}. Using the same approach, we go to the IR to find the -layout object which prints bar lines. Going via @emph{Backend} and -@emph{All layout objects} we find there is a layout object called -@code{BarLine}. Its properties include two that control its -visibility: @code{break-visibility} and @code{stencil}. Barline also -supports a number of interfaces, including the @code{grob-interface}, -where we find the @code{transparent} and the @code{color} properties. -All of these can affect the visibility of bar lines (and, of course, -by extension, many other layout objects too.) Let's consider each of -these in turn. - -@subheading stencil - -@cindex stencil property - -This property controls the appearance of the bar lines by specifying -the symbol (glyph) which should be printed. In common -with many other properties, it can be set to print nothing by -setting its value to @code{#f}. Let's try it, as before, omitting -the implied Context, @code{Voice}: - -@cindex BarLine, example of overriding -@cindex stencil property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -{ - \time 12/16 - \override BarLine #'stencil = ##f - c4 b8 c d16 c d8 | - g, a16 b8 c d4 e16 | - e8 -} -@end lilypond - -The bar lines are still printed. What is wrong? Go back to the IR -and look again at the page giving the properties of BarLine. At the -top of the page it says @qq{Barline objects are created by: -Bar_engraver}. Go to the @code{Bar_engraver} page. At the bottom it -gives a list of Contexts in which the bar engraver operates. All of -them are of the type @code{Staff}, so the reason the @code{\override} -command failed to work as expected is because @code{Barline} is not in -the default @code{Voice} context. If the context is specified -incorrectly, the command simply does not work. No error message is -produced, and nothing is logged in the log file. Let's try correcting -it by adding the correct context: - -@cindex BarLine, example of overriding -@cindex stencil property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -{ - \time 12/16 - \override Staff.BarLine #'stencil = ##f - c4 b8 c d16 c d8 | - g, a16 b8 c d4 e16 | - e8 -} -@end lilypond - -Now the bar lines have vanished. - -Note, though, that setting the @code{stencil} property to @code{#f} -will cause errors when the dimensions of the object are required for -correct processing. For example, errors will be generated if the -@code{stencil} property of the @code{NoteHead} object is set to -@code{#f}. If this is the case, you can instead use the -@code{point-stencil} function, which sets the stencil to a object -with zero size: - -@lilypond[quote,verbatim,relative=2] -{ - c c - \once \override NoteHead #'stencil = #point-stencil - c c -} -@end lilypond - -@subheading break-visibility - -@cindex break-visibility property - -We see from the @code{BarLine} properties in the IR that the -@code{break-visibility} property requires a vector of three booleans. -These control respectively whether bar lines are printed at the end of -a line, in the middle of lines, and at the beginning of lines. For -our example we want all bar lines to be suppressed, so the value we -need is @code{'#(#f #f #f)}. Let's try that, remembering to include -the @code{Staff} context. Note also that in writing this value we -have @code{#'#} before the opening bracket. The @code{'#} is required -as part of the value to introduce a vector, and the first @code{#} is -required, as always, to precede the value itself in the -@code{\override} command. - -@cindex BarLine, example of overriding -@cindex break-visibility property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -{ - \time 12/16 - \override Staff.BarLine #'break-visibility = #'#(#f #f #f) - c4 b8 c d16 c d8 | - g, a16 b8 c d4 e16 | - e8 -} -@end lilypond - -And we see this too removes all the bar lines. - -@subheading transparent - -@cindex transparent property -@cindex transparency - -We see from the properties specified in the @code{grob-interface} page -in the IR that the @code{transparent} property is a boolean. This -should be set to @code{#t} to make the grob transparent. In this next -example let us make the time signature invisible rather than the bar -lines. To do this we need to find the grob name for the time -signature. Back to the @q{All layout objects} page in the IR to find -the properties of the @code{TimeSignature} layout object. This is -produced by the @code{Time_signature_engraver} which you can check -also lives in the @code{Staff} context and also supports the -@code{grob-interface}. So the command to make the time signature -transparent is: - -@cindex TimeSignature, example of overriding -@cindex transparent property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -{ - \time 12/16 - \override Staff.TimeSignature #'transparent = ##t - c4 b8 c d16 c d8 | - g, a16 b8 c d4 e16 | - e8 -} -@end lilypond - -@noindent -The time signature is gone, but this command leaves a gap where -the time signature should be. Maybe this is what is wanted for -an exercise for the student to fill it in, but in other -circumstances a gap might be undesirable. To remove it, the -stencil for the time signature should be set to @code{#f} -instead: - -@cindex TimeSignature, example of overriding -@cindex stencil property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -{ - \time 12/16 - \override Staff.TimeSignature #'stencil = ##f - c4 b8 c d16 c d8 | - g, a16 b8 c d4 e16 | - e8 -} -@end lilypond - -@noindent -and the difference is obvious: setting the stencil to @code{#f} -removes the object entirely; making the object @code{transparent} -leaves it where it is, but makes it invisible. - -@subheading color - -@cindex color property - -Finally let us try making the bar lines invisible by coloring -them white. (There is a difficulty with this in that the -white bar line may or may not blank out the staff lines where -they cross. You may see in some of the examples below that this -happens unpredictably. The details of why this is so and how to -control it are covered in @ruser{Painting objects white}. But at -the moment we are learning about color, so please just accept this -limitation for now.) - -The @code{grob-interface} specifies that the -color property value is a list, but there is no -explanation of what that list should be. The list it -requires is actually a list of values in internal units, -but, to avoid having to know what these are, several ways -are provided to specify colors. The first way is to use one -of the @q{normal} colors listed in the first table in -@ruser{List of colors}. To set the bar lines to white -we write: - -@cindex BarLine, example of overriding -@cindex color property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -{ - \time 12/16 - \override Staff.BarLine #'color = #white - c4 b8 c d16 c d8 | - g, a16 b8 c d4 e16 | - e8 -} -@end lilypond - -@noindent -and again, we see the bar lines are not visible. Note that -@emph{white} is not preceded by an apostrophe -- it is not -a symbol, but a @emph{function}. When called, it provides -the list of internal values required to set the color to -white. The other colors in the normal list are functions -too. To convince yourself this is working you might like -to change the color to one of the other functions in the -list. - -@cindex color, X11 -@cindex X11 colors - -@funindex x11-color - -The second way of changing the color is to use the list of -X11 color names in the second list in @ruser{List of colors}. -However, these must be preceded by another function, which -converts X11 color names into the list of internal values, -@code{x11-color}, like this: - -@cindex BarLine, example of overriding -@cindex color property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -{ - \time 12/16 - \override Staff.BarLine #'color = #(x11-color 'white) - c4 b8 c d16 c d8 | - g, a16 b8 c d4 e16 | - e8 -} -@end lilypond - -@noindent -Note that in this case the function @code{x11-color} takes -a symbol as an argument, so the symbol must be preceded by -an apostrophe and the two enclosed in brackets. - -@cindex rgb colors -@cindex color, rgb - -@funindex rgb-color - -There is yet a third function, one which converts RGB values into -internal colors -- the @code{rgb-color} function. This takes -three arguments giving the intensities of the red, green and -blue colors. These take values in the range 0 to 1. So to -set the color to red the value should be @code{(rgb-color 1 0 0)} -and to white it should be @code{(rgb-color 1 1 1)}: - -@cindex BarLine, example of overriding -@cindex color property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -{ - \time 12/16 - \override Staff.BarLine #'color = #(rgb-color 1 1 1) - c4 b8 c d16 c d8 | - g, a16 b8 c d4 e16 | - e8 -} -@end lilypond - -Finally, there is also a grey scale available as part of the -X11 set of colors. These range from black, @code{'grey0'}, -to white, @code{'grey100}, in steps of 1. Let's illustrate -this by setting all the layout objects in our example to -various shades of grey: - -@cindex StaffSymbol, example of overriding -@cindex TimeSignature, example of overriding -@cindex Clef, example of overriding -@cindex NoteHead, example of overriding -@cindex Stem, example of overriding -@cindex BarLine, example of overriding -@cindex color property, example -@cindex x11-color, example of using - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -{ - \time 12/16 - \override Staff.StaffSymbol #'color = #(x11-color 'grey30) - \override Staff.TimeSignature #'color = #(x11-color 'grey60) - \override Staff.Clef #'color = #(x11-color 'grey60) - \override Voice.NoteHead #'color = #(x11-color 'grey85) - \override Voice.Stem #'color = #(x11-color 'grey85) - \override Staff.BarLine #'color = #(x11-color 'grey10) - c4 b8 c d16 c d8 | - g, a16 b8 c d4 e16 | - e8 -} -@end lilypond - -@noindent -Note the contexts associated with each of the layout objects. -It is important to get these right, or the commands will not -work! Remember, the context is the one in which the appropriate -engraver is placed. The default context for engravers can be -found by starting from the layout object, going from there to -the engraver which produces it, and on the engraver page in the -IR it tells you in which context the engraver will normally be -found. - - -@node Size of objects -@subsection Size of objects - -@cindex changing size of objects -@cindex size of objects -@cindex objects, size of -@cindex objects, changing size of - -Let us begin by looking again at the earlier example -see @ref{Nesting music expressions}) which showed -how to introduce a new temporary staff, as in an @rglos{ossia}. - -@cindex alignAboveContext property, example -@cindex @code{\with}, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\new Staff ="main" { - \relative g' { - r4 g8 g c4 c8 d | - e4 r8 - << - { f c c } - \new Staff \with { - alignAboveContext = #"main" } - { f8 f c } - >> - r4 | - } - } -@end lilypond - -Ossia are normally written without clef and time signature, and -are usually printed slightly smaller than the main staff. We -already know now how to remove the clef and time signature -- -we simply set the stencil of each to @code{#f}, as follows: - -@cindex alignAboveContext property, example -@cindex @code{\with}, example -@cindex stencil property, example -@cindex Clef, example of overriding -@cindex TimeSignature, example of overriding - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\new Staff ="main" { - \relative g' { - r4 g8 g c4 c8 d | - e4 r8 - << - { f c c } - \new Staff \with { - alignAboveContext = #"main" - } - { - \override Staff.Clef #'stencil = ##f - \override Staff.TimeSignature #'stencil = ##f - { f8 f c } - } - >> - r4 | - } -} -@end lilypond - -@noindent -where the extra pair of braces after the @code{\with} clause are -required to ensure the enclosed overrides and music are applied -to the ossia staff. - -But what is the difference between modifying the staff context by -using @code{\with} and modifying the stencils of the clef and the -time signature with \override? The main difference is that -changes made in a @code{\with} clause are made at the time the -context is created, and remain in force as the @strong{default} -values for the duration of that context, whereas -@code{\set} or @code{\override} commands embedded in the -music are dynamic -- they make changes synchronized with -a particular point in the music. If changes are unset or -reverted using @code{\unset} or @code{\revert} they return to -their default values, which will be the ones set in the -@code{\with} clause, or if none have been set there, the normal -default values. - -Some context properties can be modified only in @code{\with} clauses. -These are those properties which cannot sensibly be changed after the -context has been created. @code{alignAboveContext} and its partner, -@code{alignBelowContext}, are two such properties -- once the staff -has been created its alignment is decided and it would make no sense -to try to change it later. - -The default values of layout object properties can also be set -in @code{\with} clauses. Simply use the normal @code{\override} -command leaving out the context name, since this is unambiguously -defined as the context which the @code{\with} clause is modifying. -If fact, an error will be generated if a context is specified -in this location. - -So we could replace the example above with - -@cindex alignAboveContext property, example -@cindex @code{\with}, example -@cindex Clef, example of overriding -@cindex TimeSignature, example of overriding - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\new Staff ="main" { - \relative g' { - r4 g8 g c4 c8 d | - e4 r8 - << - { f c c } - \new Staff \with { - alignAboveContext = #"main" - % Don't print clefs in this staff - \override Clef #'stencil = ##f - % Don't print time signatures in this staff - \override TimeSignature #'stencil = ##f - } - { f8 f c } - >> - r4 | - } -} -@end lilypond - -Finally we come to changing the size of layout objects. - -Some layout objects are created as glyphs selected from a typeface -font. These include note heads, accidentals, markup, clefs, time -signatures, dynamics and lyrics. Their size is changed by modifying -the @code{font-size} property, as we shall shortly see. Other layout -objects such as slurs and ties -- in general, spanner objects -- are -drawn individually, so there is no @code{font-size} associated with -them. These objects generally derive their size from the objects to -which they are attached, so usually there is no need to change their -size manually. Still other properties such as the length of stems and -bar lines, thickness of beams and other lines, and the separation of -staff lines all need to be modified in special ways. - -Returning to the ossia example, let us first change the font-size. -We can do this in two ways. We can either change the size of the -fonts of each object type, like @code{NoteHead}s with commands -like - -@example -\override NoteHead #'font-size = #-2 -@end example - -or we can change the size of all fonts by setting a special -property, @code{fontSize}, using @code{\set}, or by including -it in a @code{\with} clause (but without the @code{\set}). - -@example -\set fontSize = #-2 -@end example - -Both of these statements would cause the font size to be reduced -by 2 steps from its previous value, where each -step reduces or increases the size by approximately 12%. - -Let's try it in our ossia example: - -@cindex alignAboveContext property, example -@cindex @code{\with}, example -@cindex Clef, example of overriding -@cindex TimeSignature, example of overriding -@cindex fontSize property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\new Staff ="main" { - \relative g' { - r4 g8 g c4 c8 d | - e4 r8 - << - { f c c } - \new Staff \with { - alignAboveContext = #"main" - \override Clef #'stencil = ##f - \override TimeSignature #'stencil = ##f - % Reduce all font sizes by ~24% - fontSize = #-2 - } - { f8 f c } - >> - r4 | - } -} -@end lilypond - -This is still not quite right. The note heads and flags are -smaller, but the stems are too long in proportion and the -staff lines are spaced too widely apart. These need to be -scaled down in proportion to the font reduction. The next -sub-section discusses how this is done. - -@node Length and thickness of objects -@subsection Length and thickness of objects - -@cindex distances -@cindex thickness -@cindex length -@cindex magstep -@cindex size, changing -@cindex stem length, changing -@cindex staff line spacing, changing - -Distances and lengths in LilyPond are generally measured in -staff-spaces, the distance between adjacent lines in the staff, -(or occasionally half staff spaces) while most @code{thickness} -properties are measured in units of an internal property called -@code{line-thickness.} For example, by default, the lines of -hairpins are given a thickness of 1 unit of @code{line-thickness}, -while the @code{thickness} of a note stem is 1.3. Note, though, -that some thickness properties are different; for example, the -thickness of beams is measured in staff-spaces. - -So how are lengths to be scaled in proportion to the font size? -This can be done with the help of a special function called -@code{magstep} provided for exactly this purpose. It takes -one argument, the change in font size (#-2 in the example above) -and returns a scaling factor suitable for reducing other -objects in proportion. It is used like this: - -@cindex alignAboveContext property, example -@cindex @code{\with}, example -@cindex Clef, example of overriding -@cindex TimeSignature, example of overriding -@cindex fontSize property, example -@cindex StaffSymbol, example of overriding -@cindex magstep function, example of using -@cindex staff-space property, example -@cindex stencil property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\new Staff ="main" { - \relative g' { - r4 g8 g c4 c8 d | - e4 r8 - << - { f c c } - \new Staff \with { - alignAboveContext = #"main" - \override Clef #'stencil = ##f - \override TimeSignature #'stencil = ##f - fontSize = #-2 - % Reduce stem length and line spacing to match - \override StaffSymbol #'staff-space = #(magstep -2) - } - { f8 f c } - >> - r4 | - } -} -@end lilypond - -@noindent -Since the length of stems and many other length-related properties are -always calculated relative to the value of the @code{staff-space} -property these are automatically scaled down in length too. Note that -this affects only the vertical scale of the ossia -- the horizontal -scale is determined by the layout of the main music in order to remain -synchronized with it, so it is not affected by any of these changes in -size. Of course, if the scale of all the main music were changed in -this way then the horizontal spacing would be affected. This is -discussed later in the layout section. - -This, then, completes the creation of an ossia. The sizes and -lengths of all other objects may be modified in analogous ways. - -For small changes in scale, as in the example above, the -thickness of the various drawn lines such as bar lines, -beams, hairpins, slurs, etc does not usually require global -adjustment. If the thickness of any particular layout object -needs to be adjusted this can be best achieved by overriding its -@code{thickness} property. An example of changing the thickness -of slurs was shown above in @ref{Properties of layout objects}. -The thickness of all drawn objects (i.e., those not produced -from a font) may be changed in the same way. - - -@node Placement of objects -@section Placement of objects - -@menu -* Automatic behavior:: -* Within-staff objects:: -* Outside-staff objects:: -@end menu - - -@node Automatic behavior -@subsection Automatic behavior - -@cindex within-staff objects -@cindex outside-staff objects -@cindex objects, within-staff -@cindex objects, outside-staff - -There are some objects in musical notation that belong to -the staff and there are other objects that should be -placed outside the staff. These are called within-staff -objects and outside-staff objects respectively. - -Within-staff objects are those that are located on the staff --- note heads, stems, accidentals, etc. The positions of -these are usually fixed by the music itself -- they are -vertically positioned on specific lines of the staff or are -tied to other objects that are so positioned. Collisions of -note heads, stems and accidentals in closely set chords are -normally avoided automatically. There are commands and -overrides which can modify this automatic behavior, as we -shall shortly see. - -Objects belonging outside the staff include things such as -rehearsal marks, text and dynamic markings. LilyPond's rule for -the vertical placement of outside-staff objects is to place them -as close to the staff as possible but not so close that they -collide with any other object. LilyPond uses the -@code{outside-staff-priority} property to determine the order in -which the objects should be placed, as follows. - -First, LilyPond places all the within-staff objects. -Then it sorts the outside-staff objects according to their -@code{outside-staff-priority}. The outside-staff objects are -taken one by one, beginning with the object with the lowest -@code{outside-staff-priority}, and placed so that they do not -collide with any objects that have already been placed. That is, -if two outside-staff grobs are competing for the same space, the -one with the lower @code{outside-staff-priority} will be placed -closer to the staff. If two objects have the same -@code{outside-staff-priority} the one encountered first will be -placed closer to the staff. - -In the following example all the markup texts have the same -priority (since it is not explicitly set). Note that @q{Text3} -is automatically positioned close to the staff again, nestling -under @q{Text2}. - -@cindex markup example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -c2^"Text1" -c^"Text2" -c^"Text3" -c^"Text4" -@end lilypond - -Staves are also positioned, by default, as closely together as -possible (subject to a minimum separation). If notes project -a long way towards an adjacent staff they will force the -staves further apart only if an overlap of the notation -would otherwise occur. The following example demonstrates -this @q{nestling} of the notes on adjacent staves: - -@lilypond[quote,ragged-right,verbatim] -<< - \new Staff { - \relative c' { c a, } - } - \new Staff { - \relative c'''' { c a, } - } ->> -@end lilypond - - -@node Within-staff objects -@subsection Within-staff objects - -We have already seen how the commands @code{\voiceXXX} affect -the direction of slurs, ties, fingering and -everything else which depends on the direction of the stems. -These commands are essential when writing polyphonic music to -permit interweaving melodic lines to be distinguished. -But occasionally it may be necessary to override this automatic -behavior. This can be done for whole sections of music or even -for an individual note. The property which controls this -behavior is the @code{direction} property of each layout object. -We first explain what this does, and then introduce a number of -ready-made commands which avoid your having to code explicit -overrides for the more common modifications. - -Some layout objects like slurs and ties curve, bend or point -either up or down; others like stems and flags also move to -right or left when they point up or down. This is controlled -automatically when @code{direction} is set. - -@cindex down -@cindex up -@cindex center -@cindex neutral - -The following example shows in bar 1 the default behavior of stems, -with those on high notes pointing down and those on low notes pointing -up, followed by four notes with all stems forced down, four notes with -all stems forced up, and finally four notes reverted back to the -default behavior. - -@cindex Stem, example of overriding -@cindex direction property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -a4 g c a -\override Stem #'direction = #DOWN -a g c a -\override Stem #'direction = #UP -a g c a -\revert Stem #'direction -a g c a -@end lilypond - -Here we use the constants @code{DOWN} and @code{UP}. -These have the values @code{-1} and @code{+1} respectively, and -these numerical values may be used instead. The value @code{0} -may also be used in some cases. It is simply treated as meaning -@code{UP} for stems, but for some objects it means @q{center}. -There is a constant, @code{CENTER} which has the value @code{0}. - -However, these explicit overrides are not usually used, as there are -simpler equivalent predefined commands available. Here is a table of -the commonest. The meaning of each is stated where it is not obvious. - -@multitable @columnfractions .2 .2 .25 .35 -@headitem Down/Left - @tab Up/Right - @tab Revert - @tab Effect -@item @code{\arpeggioArrowDown} - @tab @code{\arpeggioArrowUp} - @tab @code{\arpeggioNormal} - @tab Arrow is at bottom, at top, or no arrow -@item @code{\dotsDown} - @tab @code{\dotsUp} - @tab @code{\dotsNeutral} - @tab Direction of movement to avoid staff lines -@item @code{\dynamicDown} - @tab @code{\dynamicUp} - @tab @code{\dynamicNeutral} - @tab -@item @code{\phrasingSlurDown} - @tab @code{\phrasingSlurUp} - @tab @code{\phrasingSlurNeutral} - @tab Note: distinct from slur commands -@item @code{\slurDown} - @tab @code{\slurUp} - @tab @code{\slurNeutral} - @tab -@item @code{\stemDown} - @tab @code{\stemUp} - @tab @code{\stemNeutral} - @tab -@item @code{\textSpannerDown} - @tab @code{\textSpannerUp} - @tab @code{\textSpannerNeutral} - @tab Text entered as spanner is below/above staff -@item @code{\tieDown} - @tab @code{\tieUp} - @tab @code{\tieNeutral} - @tab -@item @code{\tupletDown} - @tab @code{\tupletUp} - @tab @code{\tupletNeutral} - @tab Tuplets are below/above notes -@end multitable - -Note that these predefined commands may @strong{not} be -preceded by @code{\once}. If you wish to limit the -effect to a single note you must either use the equivalent -@code{\once \override} command or use the predefined command -followed after the affected note by the corresponding -@code{\xxxNeutral} command. - -@subheading Fingering - -@cindex fingering, placement -@cindex fingering, chords - -The placement of fingering on single notes can also be controlled -by the @code{direction} property, but changing @code{direction} -has no effect on chords. As we shall see, there are special -commands which allow the fingering of individual notes -of chords to be controlled, with the fingering being placed -above, below, to the left or to the right of each note. - -First, here's the effect of @code{direction} on the fingering -attached to single notes. The first bar shows the default -behaviour, and the following two bars shows the effect of -specifying @code{DOWN} and @code{UP}: - -@cindex Fingering, example of overriding -@cindex direction property, example - -@lilypond[quote,verbatim,relative=2] -c-5 a-3 f-1 c'-5 -\override Fingering #'direction = #DOWN -c-5 a-3 f-1 c'-5 -\override Fingering #'direction = #UP -c-5 a-3 f-1 c'-5 -@end lilypond - -However, overriding the @code{direction} property is not the -easiest way of manually setting the fingering above or below -the notes; using @code{_} or @code{^} instead of @code{-} before -the fingering number is usually preferable. Here is the previous -example using this method: - -@cindex fingering example - -@lilypond[quote,verbatim,relative=2] -c-5 a-3 f-1 c'-5 -c_5 a_3 f_1 c'_5 -c^5 a^3 f^1 c'^5 -@end lilypond - -The @code{direction} property is ignored for chords, but the -directional prefixes, @code{_} and @code{^} do work. By default, -the fingering is automatically placed both above and below the -notes of a chord, as shown: - -@cindex fingering example - -@lilypond[quote,verbatim,relative=2] - - - -@end lilypond - -@noindent -but this may be overridden to manually force all or any of the -individual fingering numbers above or below: - -@cindex fingering example - -@lilypond[quote,verbatim,relative=2] - - - -@end lilypond - -Even greater control over the placement of fingering of the -individual notes in a chord is possible by using the -@code{\set fingeringOrientations} command. The format of this -command is: - -@example -@code{\set fingeringOrientations = #'([up] [left/right] [down])} -@end example - -@noindent -@code{\set} is used because @code{fingeringOrientations} is a -property of the @code{Voice} context, created and used by the -@code{New_fingering_engraver}. - -The property may be set to a list of one to three values. -It controls whether fingerings may be placed above (if -@code{up} appears in the list), below (if @code{down} appears), -to the left (if @code{left} appears, or to the right -(if @code{right} appears). Conversely, if a location is not -listed, no fingering is placed there. LilyPond takes these -constraints and works out the best placement for the fingering -of the notes of the following chords. Note that @code{left} and -@code{right} are mutually exclusive -- fingering may be placed -only on one side or the other, not both. - -@warning{To control the placement of the fingering of a single -note using this command it is necessary to write it as a single -note chord by placing angle brackets round it.} - -Here are a few examples: - -@cindex fingering example -@cindex @code{\set}, example of using -@cindex fingeringOrientations property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] -\set fingeringOrientations = #'(left) - -< c-1 e-2 g-3 b-5 > 4 -\set fingeringOrientations = #'(left) - -< c-1 e-2 g-3 b-5 > 4 -\set fingeringOrientations = #'(up left down) - -< c-1 e-2 g-3 b-5 > 4 -\set fingeringOrientations = #'(up left) - -< c-1 e-2 g-3 b-5 > 4 -\set fingeringOrientations = #'(right) - -< c-1 e-2 g-3 b-5 > 4 -@end lilypond - -@noindent -If the fingering seems a little crowded the @code{font-size} -could be reduced. The default value can be seen from the -@code{Fingering} object in the IR to be @code{-5}, so let's -try @code{-7}: - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] -\override Fingering #'font-size = #-7 -\set fingeringOrientations = #'(left) - -< c-1 e-2 g-3 b-5 > 4 -\set fingeringOrientations = #'(left) - -< c-1 e-2 g-3 b-5 > 4 -\set fingeringOrientations = #'(up left down) - -< c-1 e-2 g-3 b-5 > 4 -\set fingeringOrientations = #'(up left) - -< c-1 e-2 g-3 b-5 > 4 -\set fingeringOrientations = #'(right) - -< c-1 e-2 g-3 b-5 > 4 -@end lilypond - -@node Outside-staff objects -@subsection Outside-staff objects - -Outside-staff objects are automatically placed to avoid collisions. -Objects with the lower value of the @code{outside-staff-priority} -property are placed nearer to the staff, and other outside-staff -objects are then raised as far as necessary to avoid collisions. -The @code{outside-staff-priority} is defined in the -@code{grob-interface} and so is a property of all layout objects. -By default it is set to @code{#f} for all within-staff objects, -and to a numerical value appropriate to each outside-staff object -when the object is created. The following table shows -the default numerical values for some of the commonest -outside-staff objects which are, by default, placed in the -@code{Staff} or @code{Voice} contexts. - -@multitable @columnfractions .3 .3 .3 -@headitem Layout Object - @tab Priority - @tab Controls position of: -@item @code{MultiMeasureRestText} - @tab @code{450} - @tab Text over full-bar rests -@item @code{TextScript} - @tab @code{450} - @tab Markup text -@item @code{OttavaBracket} - @tab @code{400} - @tab Ottava brackets -@item @code{TextSpanner} - @tab @code{350} - @tab Text spanners -@item @code{DynamicLineSpanner} - @tab @code{250} - @tab All dynamic markings -@item @code{VoltaBracketSpanner} - @tab @code{100} - @tab Volta brackets -@item @code{TrillSpanner} - @tab @code{50} - @tab Spanning trills -@end multitable - -Here is an example showing the default placement of some of -these. - -@cindex text spanner -@cindex ottava bracket - -@funindex \startTextSpan -@funindex startTextSpan -@funindex \stopTextSpan -@funindex stopTextSpan - -@cindex TextSpanner, example of overriding -@cindex bound-details property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] -% Set details for later Text Spanner -\override TextSpanner #'(bound-details left text) - = \markup { \small \bold Slower } -% Place dynamics above staff -\dynamicUp -% Start Ottava Bracket -\ottava #1 -c' \startTextSpan -% Add Dynamic Text -c\pp -% Add Dynamic Line Spanner -c\< -% Add Text Script -c^Text -c c -% Add Dynamic Text -c\ff c \stopTextSpan -% Stop Ottava Bracket -\ottava #0 -c, c c c -@end lilypond - -This example also shows how to create Text Spanners -- -text with extender lines above a section of music. The -spanner extends from the @code{\startTextSpan} command to -the @code{\stopTextSpan} command, and the format of the -text is defined by the @code{\override TextSpanner} command. -For more details see @ruser{Text spanners}. - -It also shows how ottava brackets are created. - -@cindex tweaking bar number placement -@cindex bar numbers, tweaking placement -@cindex tweaking metronome mark placement -@cindex metronome mark, tweaking placement -@cindex tweaking rehearsal mark placement -@cindex rehearsal marks, tweaking placement - -Note that bar numbers, metronome marks and rehearsal marks are not -shown. By default these are created in the @code{Score} context and -their @code{outside-staff-priority} is ignored relative to the layout -objects which are created in the @code{Staff} context. If you wish to -place bar numbers, metronome marks or rehearsal marks in accordance -with the value of their @code{outside-staff-priority} the -@code{Bar_number_engraver}, @code{Metronome_mark_engraver} or -@code{Mark_engraver} respectively should be removed from the -@code{Score} context and placed in the top @code{Staff} context. If -this is done, these marks will be given the following default -@code{outside-staff-priority} values: - -@multitable @columnfractions .3 .3 -@headitem Layout Object @tab Priority -@item @code{RehearsalMark} @tab @code{1500} -@item @code{MetronomeMark} @tab @code{1000} -@item @code{BarNumber} @tab @code{ 100} -@end multitable - -If the default values of @code{outside-staff-priority} do not give you -the placing you want, the priority of any of the objects may be -overridden. Suppose we would like the ottava bracket to be placed -below the text spanner in the example above. All we need to do is to -look up the priority of @code{OttavaBracket} in the IR or in the -tables above, and reduce it to a value lower than that of a -@code{TextSpanner}, remembering that @code{OttavaBracket} is created -in the @code{Staff} context: - -@cindex TextSpanner, example of overriding -@cindex bound-details property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] -% Set details for later Text Spanner -\override TextSpanner #'(bound-details left text) - = \markup { \small \bold Slower } -% Place dynamics above staff -\dynamicUp -%Place following Ottava Bracket below Text Spanners -\once \override Staff.OttavaBracket #'outside-staff-priority = #340 -% Start Ottava Bracket -\ottava #1 -c' \startTextSpan -% Add Dynamic Text -c\pp -% Add Dynamic Line Spanner -c\< -% Add Text Script -c^Text -c c -% Add Dynamic Text -c\ff c \stopTextSpan -% Stop Ottava Bracket -\ottava #0 -c, c c c -@end lilypond - -@cindex slurs and outside-staff-priority -@cindex slurs and articulations -@cindex articulations and slurs - -Slurs by default are classed as within-staff objects, but -they often appear above the staff if the notes to -which they are attached are high on the staff. This can push -outside-staff objects such as articulations too high, as the slur -will be placed first. The @code{avoid-slur} property of the -articulation can be set to @code{'inside} to bring the articulation -inside the slur, but the @code{avoid-slur} property is effective -only if the @code{outside-staff-priority} is also set to @code{#f}. -Alternatively, the @code{outside-staff-priority} of the slur -can be set to a numerical value to cause it to be placed along with -other outside-staff objects according to that value. Here's an -example showing the effect of the two methods: - -@lilypond[quote,verbatim,relative=2] -c4( c^\markup\tiny\sharp d4.) c8 -c4( -\once \override TextScript #'avoid-slur = #'inside -\once \override TextScript #'outside-staff-priority = ##f -c^\markup\tiny\sharp d4.) c8 -\once \override Slur #'outside-staff-priority = #500 -c4( c^\markup\tiny\sharp d4.) c8 -@end lilypond - -Changing the @code{outside-staff-priority} can also be used to -control the vertical placement of individual objects, although -the results may not always be desirable. Suppose we would -like @qq{Text3} to be placed above @qq{Text4} in the example -under Automatic behavior, above (see @ref{Automatic behavior}). -All we need to do is to look up the priority of @code{TextScript} -in the IR or in the tables above, and increase the priority of -@qq{Text3} to a higher value: - -@cindex TextScript, example of overriding -@cindex outside-staff-priority property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -c2^"Text1" -c^"Text2" -\once \override TextScript #'outside-staff-priority = #500 -c^"Text3" -c^"Text4" -@end lilypond - -This certainly lifts @qq{Text3} above @qq{Text4} but it also lifts it -above @qq{Text2}, and @qq{Text4} now drops down. Perhaps this is not -so good. What we would really like to do is to position all the -annotation at the same distance above the staff. To do this, we -clearly will need to space the notes out horizontally to make more -room for the text. This is done using the @code{textLengthOn} -command. - -@subheading \textLengthOn - -@cindex notes, spreading out with text - -@funindex \textLengthOn -@funindex textLengthOn -@funindex \textLengthOff -@funindex textLengthOff - -By default, text produced by markup takes up no horizontal space -as far as laying out the music is concerned. The @code{\textLengthOn} -command reverses this behavior, causing the notes to be spaced -out as far as is necessary to accommodate the text: - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\textLengthOn % Cause notes to space out to accommodate text -c2^"Text1" -c^"Text2" -c^"Text3" -c^"Text4" -@end lilypond - -The command to revert to the default behavior is -@code{\textLengthOff}. Remember @code{\once} only works with -@code{\override}, @code{\set}, @code{\revert} or @code{unset}, -so cannot be used with @code{\textLengthOn}. - -@cindex markup text, allowing collisions - -Markup text will also avoid notes which project above the staff. -If this is not desired, the automatic displacement upwards may -be turned off by setting the priority to @code{#f}. Here's an -example to show how markup text interacts with such notes. - -@cindex TextScript, example of overriding -@cindex outside-staff-priority property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -% This markup is short enough to fit without collision -c2^"Tex" -c''2 -R1 -% This is too long to fit, so it is displaced upwards -c,,2^"Text" -c''2 -R1 -% Turn off collision avoidance -\once \override TextScript #'outside-staff-priority = ##f -c,,2^"Long Text " -c''2 -R1 -% Turn off collision avoidance -\once \override TextScript #'outside-staff-priority = ##f -\textLengthOn % and turn on textLengthOn -c,,2^"Long Text " % Spaces at end are honored -c''2 -@end lilypond - - -@subheading Dynamics - -@cindex tweaking dynamics placement -@cindex dynamics, tweaking placement - -Dynamic markings will normally be positioned beneath the -staff, but may be positioned above with the @code{dynamicUp} -command. They will be positioned vertically relative to the -note to which they are attached, and will float below (or above) -all within-staff objects such as phrasing slurs and bar numbers. -This can give quite acceptable results, as this example -shows: - -@lilypond[quote,fragment,ragged-right,verbatim,relative=1] -\clef "bass" -\key aes \major -\time 9/8 -\dynamicUp -bes4.~\f\< \( bes4 bes8 des4\ff\> c16 bes\! | -ees,2.~\)\mf ees4 r8 | -@end lilypond - -However, if the notes and attached dynamics are close -together the automatic placement will avoid collisions -by displacing later dynamic markings further away, but this may -not be the optimum placement, as this rather artificial example -shows: - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\dynamicUp -a4\f b\mf c\mp b\p -@end lilypond - -@noindent -Should a similar situation arise in @q{real} music, it may be -preferable to space out the notes a little further, so the dynamic -markings can all fit at the same vertical distance from the staff. We -were able to do this for markup text by using the @code{\textLengthOn} -command, but there is no equivalent command for dynamic marks. So we -shall have to work out how to do this using @code{\override} commands. - -@subheading Grob sizing - -@cindex grob sizing -@cindex sizing grobs - -First we must learn how grobs are sized. All grobs have a -reference point defined within them which is used to position -them relative to their parent object. This point in the grob -is then positioned at a horizontal distance, @code{X-offset}, -and at a vertical distance, @code{Y-offset}, from its parent. -The horizontal extent of the object is given by a pair of -numbers, @code{X-extent}, which say where the left and right -edges are relative to the reference point. The vertical extent -is similarly defined by a pair of numbers, @code{Y-extent}. -These are properties of all grobs which support the -@code{grob-interface}. - -@cindex @code{extra-spacing-width} - -By default, outside-staff objects are given a width of zero so -that they may overlap in the horizontal direction. This is done -by the trick of adding infinity to the leftmost extent and -minus infinity to the rightmost extent by setting the -@code{extra-spacing-width} to @code{'(+inf.0 . -inf.0)}. So -to ensure they do not overlap in the horizontal direction we -must override this value of @code{extra-spacing-width} to -@code{'(0 . 0)} so the true width shines through. This is -the command to do this for dynamic text: - -@example -\override DynamicText #'extra-spacing-width = #'(0 . 0) -@end example - -@noindent -Let's see if this works in our previous example: - -@cindex DynamicText, example of overriding -@cindex extra-spacing-width property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\dynamicUp -\override DynamicText #'extra-spacing-width = #'(0 . 0) -a4\f b\mf c\mp b\p -@end lilypond - -@noindent -Well, it has certainly stopped the dynamic marks being -displaced, but two problems remain. The marks should be -spaced a little further apart and it would be better -if they were all the same distance from the staff. -We can solve the first problem easily. Instead of making -the @code{extra-spacing-width} zero we could add a little -more to it. The units are the space between two staff -lines, so moving the left edge half a unit to the left and the -right edge half a unit to the right should do it: - -@cindex DynamicText, example of overriding -@cindex extra-spacing-width property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\dynamicUp -% Extend width by 1 staff space -\override DynamicText #'extra-spacing-width = #'(-0.5 . 0.5) -a4\f b\mf c\mp b\p -@end lilypond - -@noindent -This looks better, but maybe we would prefer the dynamic marks -to be aligned along the same baseline rather than going up and -down with the notes. The property to do this is -@code{staff-padding} which is covered in the following section. - - -@node Collisions of objects -@section Collisions of objects - -@menu -* Moving objects:: -* Fixing overlapping notation:: -* Real music example:: -@end menu - -@node Moving objects -@subsection Moving objects - -@cindex moving overlapping objects -@cindex moving colliding objects -@cindex moving colliding grobs -@cindex objects, moving colliding -@cindex grobs, moving colliding - -This may come as a surprise, but LilyPond is not perfect. Some -notation elements can overlap. This is unfortunate, but in fact -rather rare. Usually the need to move objects is for clarity or -aesthetic reasons -- they would look better with a little more -or a little less space around them. - -There are three main approaches to resolving overlapping -notation. They should be considered in the following order: - -@enumerate -@item -The @strong{direction} of one of the overlapping objects may -be changed using the predefined commands listed above for -within-staff objects (see @ref{Within-staff objects}). -Stems, slurs, beams, ties, dynamics, text and tuplets may be -repositioned easily in this way. The limitation is that you -have a choice of only two positions, and neither may be -suitable. - -@item -The @strong{object properties}, which LilyPond uses when positioning -layout objects, may be modified using @code{\override}. The -advantages of making changes to this type of property are (a) that -some other objects will be moved automatically if necessary to make -room and (b) the single override can apply to all instances of the -same type of object. Such properties include: - -@itemize - -@item -@code{direction} - -This has already been covered in some detail -- see -@ref{Within-staff objects}. - -@item -@code{padding}, @code{left-padding}, -@code{right-padding}, @code{staff-padding} - -@cindex padding -@cindex left-padding property -@cindex padding property -@cindex right-padding property -@cindex staff-padding property - -As an object is being positioned the value of its @code{padding} -property specifies the gap that must be left between itself and the -nearest edge of the object against which it is being positioned. Note -that it is the @code{padding} value of the object @strong{being -placed} that is used; the @code{padding} value of the object which is -already placed is ignored. Gaps specified by @code{padding} can be -applied to all objects which support the -@code{side-position-interface}. - -Instead of @code{padding}, the placement of groups of accidentals -is controlled by @code{left-padding} and @code{right-padding}. -These properties are to be found in the @code{AccidentalPlacement} -object which, note, lives in the @strong{staff} context. In the -type-setting process the note heads are type-set first and then -the accidentals, if any, are added to the left of the note heads -using the @code{right-padding} property to determine the separation -from the note heads. So only the @code{right-padding} property of the -@code{AccidentalPlacement} object has any effect on the placement -of the accidentals. - -The @code{staff-padding} property is closely related to the -@code{padding} property: @code{padding} controls the minimum amount of -space between any object which supports the -@code{side-position-interface} and the nearest other object (generally -the note or the staff lines); @code{staff-padding} applies only to -those objects which are always set outside the staff -- it controls -the minimum amount of space that should be inserted between that -object and the staff. Note that @code{staff-padding} has no effect on -objects which are positioned relative to the note rather than the -staff, even though it may be overridden without error for such objects --- it is simply ignored. - -To discover which padding property is required for the object you wish -to reposition, you need to return to the IR and look up the object's -properties. Be aware that the padding properties might not be located -in the obvious object, so look in objects that appear to be related. - -All padding values are measured in staff spaces. For most -objects, this value is set by default to be around 1.0 or less -(it varies with each object). It may be overridden if a larger -(or smaller) gap is required. - -@item -@code{self-alignment-X} - -@cindex self-alignment-X property - -This property can be used to align the object to the left, to -the right, or to center it with respect to the parent object's -reference point. It may be used with all objects which support -the @code{self-alignment-interface}. In general these are objects -that contain text. The values are @code{LEFT}, @code{RIGHT} -or @code{CENTER}. Alternatively, a numerical value between -@code{-1} and @code{+1} may be specified, where @code{-1} is -left-aligned, @code{+1} is right-aligned, and numbers in between -move the text progressively from left-aligned to right-aligned. -Numerical values greater than @code{1} may be specified to move -the text even further to the left, or less than @code{-1} to -move the text even further to the right. A change of @code{1} -in the value corresponds to a movement of half the text's length. - -@item -@code{extra-spacing-width} - -@cindex extra-spacing-width property - -This property is available for all objects which support the -@code{item-interface}. It takes two numbers, the first is added -to the leftmost extent and the second is added to the rightmost -extent. Negative numbers move the edge to the left, positive to -the right, so to widen an object the first number must be negative, -the second positive. Note that not all objects honor both -numbers. For example, the @code{Accidental} object only takes -notice of the first (left edge) number. - -@item -@code{staff-position} - -@cindex staff-position property - -@code{staff-position} is a property of the -@code{staff-symbol-referencer-interface}, which is supported by -objects which are positioned relative to the staff. It specifies -the vertical position of the object relative to the center line -of the staff in half staff-spaces. It is useful in resolving -collisions between layout objects like multi-measure rests, ties -and notes in different voices. - -@item -@code{force-hshift} - -@cindex force-hshift property - -Closely spaced notes in a chord, or notes occurring at the same -time in different voices, are arranged in two, occasionally more, -columns to prevent the note heads overlapping. These are called -note columns, and an object called @code{NoteColumn} is created -to lay out the notes in that column. - -The @code{force-hshift} property is a property of a @code{NoteColumn} -(actually of the @code{note-column-interface}). Changing it permits a -note column to be moved in units appropriate to a note column, -viz. the note head width of the first voice note. It should be used -in complex situations where the normal @code{\shiftOn} commands (see -@ref{Explicitly instantiating voices}) do not resolve the note -conflict. It is preferable to the @code{extra-offset} property for -this purpose as there is no need to work out the distance in -staff-spaces, and moving the notes into or out of a @code{NoteColumn} -affects other actions such as merging note heads. - -@end itemize - -@item -Finally, when all else fails, objects may be manually repositioned -relative to the staff center line vertically, or by displacing them by -any distance to a new position. The disadvantages are that the -correct values for the repositioning have to be worked out, often by -trial and error, for every object individually, and, because the -movement is done after LilyPond has placed all other objects, the user -is responsible for avoiding any collisions that might ensue. But the -main difficulty with this approach is that the repositioning values -may need to be reworked if the music is later modified. The -properties that can be used for this type of manual repositioning are: - -@table @code -@item extra-offset - -@cindex extra-offset property - -This property applies to any layout object supporting the -@code{grob-interface}. It takes a pair of numbers which specify the -extra displacement in the horizontal and vertical directions. -Negative numbers move the object to the left or down. The units are -staff-spaces. The extra displacement is made after the typesetting of -objects is finished, so an object may be repositioned anywhere without -affecting anything else. - -@item positions - -@cindex positions property - -This is most useful for manually adjusting the slope and height -of beams, slurs, and tuplets. It takes a pair of numbers -giving the position of the left and right ends of the beam, slur, -etc. relative to the center line of the staff. Units are -staff-spaces. Note, though, that slurs and phrasing slurs cannot -be repositioned by arbitrarily large amounts. LilyPond first -generates a list of possible positions for the slur and by default -finds the slur that @qq{looks best}. If the @code{positions} -property has been overridden the slur that is closest to the -requested positions is selected from the list. -@end table - -@end enumerate - -A particular object may not have all of these properties. -It is necessary to go to the IR to look up which properties -are available for the object in question. - -Here is a list of the objects which are most likely to be -involved in collisions, together with the name of the object which -should be looked up in the IR in order to discover which properties -should be used to move them. - -@multitable @columnfractions .5 .5 -@headitem Object type @tab Object name -@item Articulations @tab @code{Script} -@item Beams @tab @code{Beam} -@item Dynamics (vertically) @tab @code{DynamicLineSpanner} -@item Dynamics (horizontally) @tab @code{DynamicText} -@item Fingerings @tab @code{Fingering} -@item Rehearsal / Text marks @tab @code{RehearsalMark} -@item Slurs @tab @code{Slur} -@item Text e.g. @code{^"text"} @tab @code{TextScript} -@item Ties @tab @code{Tie} -@item Tuplets @tab @code{TupletBracket} -@end multitable - - -@node Fixing overlapping notation -@subsection Fixing overlapping notation - -Let's now see how the properties in the previous section can -help to resolve overlapping notation. - -@subheading padding property - -@cindex padding -@cindex fixing overlapping notation -@cindex overlapping notation - -The @code{padding} property can be set to increase -(or decrease) the distance between symbols that are printed -above or below notes. - -@cindex Script, example of overriding -@cindex padding property, example - -@lilypond[quote,fragment,relative=1,verbatim] -c2\fermata -\override Script #'padding = #3 -b2\fermata -@end lilypond - -@cindex MetronomeMark, example of overriding -@cindex padding property, example - -@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{Modifying properties}. - -If the @code{padding} property of an object is increased when that -object is in a stack of objects being positioned according to -their @code{outside-staff-priority}, then that object and all -objects outside it are moved. - - -@subheading left-padding and right-padding - -@cindex left-padding property -@cindex right-padding property - -The @code{right-padding} property affects the spacing between the -accidental and the note to which it applies. It is not often -required, but the following example shows one situation where it -is needed. Suppose we wish to show a chord containing both -a B-natural and a B-flat. To avoid ambiguity we would like to -precede the notes with both a natural and a flat sign. Here -are a few attempts to do this: - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] - - - -@end lilypond - -None work, with the second two showing bad collisions between -the two signs. - -One way of achieving this is to override the accidental stencil -with a markup containing the natural and flat symbols in the -order we would like, like this: - -@cindex Accidental, example of overriding -@cindex text property, example -@cindex stencil property, example -@cindex AccidentalPlacement, example of overriding -@cindex right-padding property, example - -@lilypond[quote,ragged-right,verbatim] -naturalplusflat = \markup { \natural \flat } -\relative c'' { - \once \override Accidental - #'stencil = #ly:text-interface::print - \once \override Accidental #'text = #naturalplusflat - \once \override Score.AccidentalPlacement #'right-padding = #1.5 - -} -@end lilypond - -@noindent -This necessarily uses an override for the accidental stencil which -will not be covered until later. The stencil type must be a -procedure, here changed to print the contents of the @code{text} -property of @code{Accidental}, which itself is set to be a natural -sign followed by a flat sign. These are then moved further away -from the note head by overriding @code{right-padding}. - -@noindent - -@subheading staff-padding property - -@cindex aligning objects on a baseline -@cindex objects, aligning on a baseline - -@code{staff-padding} can be used to align objects such as dynamics -along a baseline at a fixed height above the staff, rather than at a -height dependent on the position of the note to which they are -attached. It is not a property of @code{DynamicText} but of -@code{DynamicLineSpanner}. This is because the baseline should apply -equally to @strong{all} dynamics, including those created as extended -spanners. So this is the way to align the dynamic marks in the -example taken from the previous section: - -@cindex DynamicText, example of overriding -@cindex extra-spacing-width property, example -@cindex DynamicLineSpanner, example of overriding -@cindex staff-padding property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\dynamicUp -% Extend width by 1 unit -\override DynamicText #'extra-spacing-width = #'(-0.5 . 0.5) -% Align dynamics to a base line 2 units above staff -\override DynamicLineSpanner #'staff-padding = #2 -a4\f b\mf c\mp b\p -@end lilypond - - -@subheading self-alignment-X property - -The following example shows how this can resolve the collision -of a string fingering object with a note's stem by aligning the -right edge with the reference point of the parent note: - -@cindex StringNumber, example of overriding -@cindex self-alignment-X property, example - -@lilypond[quote,fragment,ragged-right,verbatim,relative=3] -\voiceOne -< a \2 > -\once \override StringNumber #'self-alignment-X = #RIGHT -< a \2 > -@end lilypond - -@subheading staff-position property - -@cindex object collision within a staff - -Multimeasure rests in one voice can collide with notes in another. -Since these rests are typeset centered between the bar lines, it -would require significant effort for LilyPond to figure out which -other notes might collide with it, since all the current collision -handling between notes and between notes and rests is done only -for notes and rests that occur at the same time. Here's an -example of a collision of this type: - -@lilypond[quote,verbatim,fragment,ragged-right, relative=1] -<< {c c c c} \\ {R1} >> -@end lilypond - -The best solution here is to move the multimeasure rest down, since -the rest is in voice two. The default in @code{\voiceTwo} (i.e. in -the second voice of a @code{<<@{...@} \\ @{...@}>>} construct) is that -@code{staff-position} is set to -4 for MultiMeasureRest, so we need to -move it, say, four half-staff spaces down to @code{-8}. - -@cindex MultiMeasureRest, example of overriding -@cindex staff-position property, example - -@lilypond[quote,verbatim,fragment,ragged-right, relative=1] -<< - {c c c c} -\\ - \override MultiMeasureRest #'staff-position = #-8 - {R1} ->> -@end lilypond - -This is better than using, for example, @code{extra-offset}, -because the ledger line above the rest is inserted automatically. - -@subheading extra-offset property - -@cindex positioning objects -@cindex positioning grobs -@cindex objects, positioning -@cindex grobs, positioning - -The @code{extra-offset} property provides complete control over the -positioning of an object both horizontally and vertically. - -In the following example, the second fingering is moved a little to -the left, and 1.8 staff space downwards: - -@cindex Fingering, example of overriding -@cindex extra-offset property, example - -@lilypond[quote,fragment,relative=1,verbatim] -\stemUp -f-5 -\once \override Fingering - #'extra-offset = #'(-0.3 . -1.8) -f-5 -@end lilypond - - -@subheading positions property - -@cindex controlling tuplets, slurs, phrasing slurs, and beams manually -@cindex manually controlling tuplets, slurs, phrasing slurs, and beams -@cindex tuplet beams, controlling manually -@cindex slurs, controlling manually -@cindex phrasing slurs, controlling manually -@cindex beams, controlling manually - -The @code{positions} property allows the position and slope of -tuplets, slurs, phrasing slurs and beams to be controlled manually. -Here's an example which has an ugly phrasing slur due to its trying to -avoid the slur on the acciaccatura. - -@lilypond[quote,verbatim,fragment,ragged-right,relative=1] -r4 \acciaccatura e8\( d8 c ~c d c d\) -@end lilypond - -@noindent -We could simply move the phrasing slur above the notes, and this -would be the preferred solution: - -@lilypond[quote,verbatim,fragment,ragged-right,relative=1] -r4 -\phrasingSlurUp -\acciaccatura e8\( d8 c ~c d c d\) -@end lilypond - -@noindent -But if there were some reason why this could not be done the -other alternative would be to move the left end of the phrasing -slur down a little using the @code{positions} property. This -also resolves the rather nasty shape. - -@cindex PhrasingSlur, example of overriding -@cindex positions property, example - -@lilypond[quote,verbatim,fragment,ragged-right,relative=1] -r4 -\once \override PhrasingSlur #'positions = #'(-4 . -3) -\acciaccatura -e8\( d8 c ~c d c d\) -@end lilypond - -Here's a further example taken from the opening of the left-hand -staff of Chopin's Prelude Op 28 No. 2. We see that the beam -collides with the upper notes: - -@lilypond[quote,verbatim,fragment,ragged-right] -{ -\clef "bass" -<< {b,8 ais, b, g,} \\ {e, g e, g} >> -<< {b,8 ais, b, g,} \\ {e, g e, g} >> -} -@end lilypond - -@noindent -This can be resolved by manually moving both ends of the beam -up from their position at 2 staff-spaces above the center line to, -say, 3: - -@cindex Beam, example of overriding -@cindex positions property, example - -@lilypond[quote,verbatim,fragment,ragged-right] -{ - \clef "bass" - << - \override Beam #'positions = #'(3 . 3) - {b,8 ais, b, g,} - \\ - {e, g e, g} - >> - << {b,8 ais, b, g,} \\ {e, g e, g} >> -} -@end lilypond - -@noindent -Note that the override continues to apply in the first voice of -the second block of quavers, but not to any of the beams in the -second voice. - -@subheading force-hshift property - -@c FIXME: formatting stuff (ie not important right now IMO) -@c @a nchor Chopin finally corrected TODOgp - -We can now see how to apply the final corrections to the Chopin -example introduced at the end of @ref{I'm hearing Voices}, which -was left looking like this: - -@lilypond[quote,verbatim,fragment,ragged-right] -\new Staff \relative c'' { - \key aes \major - << - { c2 aes4. bes8 } \\ - { aes2 f4 fes } \\ - { \voiceFour - 2 - des2 - } - >> | - 1 | -} -@end lilypond - -@noindent -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}, which is a -property of @code{NoteColumn}, 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 note head's width to the right of the note column of -the higher notes. - -Here's the final result: - -@cindex NoteColumn, example of overriding -@cindex force-hshift property, example - -@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 - - -@node Real music example -@subsection Real music example - -We end this section on Tweaks by showing the steps to be taken to -deal with a tricky example which needs several tweaks to produce -the desired output. The example has been deliberately chosen to -illustrate the use of the Notation Reference to resolve unusual -problems with notation. It is not representative of more usual -engraving process, so please do not let these difficulties put -you off! Fortunately, difficulties like these are not very common! - -The example is from Chopin's Première Ballade, Op. 23, bars 6 to -9, the transition from the opening Lento to Moderato. -Here, first, is what we want the output to look like, but to avoid -over-complicating the example too much we have left out the -dynamics, fingering and pedalling. - -@c The following should appear as music without code -@c This example should not be indexed -@lilypond[quote,ragged-right] -rhMusic = \relative c'' { - r2 - c4.\( g8 | - \once \override Tie #'staff-position = #3.5 - bes1~ | - \bar "||" - \time 6/4 - \mergeDifferentlyHeadedOn - \mergeDifferentlyDottedOn - bes2.^\markup {\bold "Moderato"} r8 - << - {c,8[ d fis bes a] | } - \\ - % Reposition the c2 to the right of the merged note - {c,8~ \once \override NoteColumn #'force-hshift = #1.0 - % Move the c2 out of the main note column so the merge will work - \shiftOnn c2} - \\ - % Stem on the d2 must be down to permit merging - {s8 \stemDown \once \override Stem #'transparent = ##t d2} - \\ - {s4 fis4.} - >> - \mergeDifferentlyHeadedOff - \mergeDifferentlyDottedOff - g2.\) -} - -lhMusic = \relative c' { - r2 2( | - 1)\arpeggio | - r2. d,,4 r4 r | - r4 -} - -\score { - \new PianoStaff << - \new Staff = "RH" << - \key g \minor - \rhMusic - >> - \new Staff = "LH" << - \key g \minor - \clef "bass" - \lhMusic - >> - >> -} -@end lilypond - -We note first that the right hand part in the third bar -requires four voices. These are the five beamed eighth notes, -the tied C, the half-note D which is merged with the eighth note -D, and the dotted quarter note F-sharp, which is also merged with -the eighth note at the same pitch. Everything else is in a single -voice, so the easiest way is to introduce these four voices -temporarily at the time they are needed. If you have forgotten -how to do this, look at @ref{I'm hearing Voices}. Let us begin -by entering the notes as two variables and setting up the staff -structure in a score block, and see what LilyPond produces by -default: - -@lilypond[quote,verbatim,ragged-right] -rhMusic = \relative c'' { - r2 c4. g8 | - bes1~ | - \time 6/4 - bes2. r8 - % Start polyphonic section of four voices - << - {c,8 d fis bes a | } - \\ - {c,8~ c2 | } - \\ - {s8 d2 | } - \\ - {s4 fis4. | } - >> - g2. -} - -lhMusic = \relative c' { - r2 2 | - 1 | - r2. d,,4 r4 r | - r4 -} - -\score { - \new PianoStaff << - \new Staff = "RH" << - \key g \minor - \rhMusic - >> - \new Staff = "LH" << - \key g \minor - \clef "bass" - \lhMusic - >> - >> -} -@end lilypond - -All the notes are right, but the appearance is far from satisfactory. -The tie clashes with the change in time signature, the beaming in the -third bar is wrong, the notes are not merged together, and several -notation elements are missing. Let's first deal with the easier -things. We can correct the beaming by inserting a beam manually, and -we can easily add the left hand slur and the right hand phrasing slur, -since these were all covered in the Tutorial. Doing this gives: - -@lilypond[quote,verbatim,ragged-right] -rhMusic = \relative c'' { - r2 c4.\( g8 | - bes1~ | - \time 6/4 - bes2. r8 - % Start polyphonic section of four voices - << - {c,8[ d fis bes a] | } - \\ - {c,8~ c2 | } - \\ - {s8 d2 | } - \\ - {s4 fis4. | } - >> - g2.\) -} - -lhMusic = \relative c' { - r2 2( | - 1) | - r2. d,,4 r4 r | - r4 -} - -\score { - \new PianoStaff << - \new Staff = "RH" << - \key g \minor - \rhMusic - >> - \new Staff = "LH" << - \key g \minor - \clef "bass" - \lhMusic - >> - >> -} -@end lilypond - -The first bar is now correct. The second bar contains an arpeggio and -is terminated by a double bar line. How do we do these, as they have -not been mentioned in this Learning Manual? This is where we need to -turn to the Notation Reference. Looking up @q{arpeggio} and @q{bar -line} in the index quickly shows us that an arpeggio is produced by -appending @code{\arpeggio} to a chord, and a double bar line is -produced by the @code{\bar "||"} command. That's easily done. We -next need to correct the collision of the tie with the time signature. -This is best done by moving the tie upwards. Moving objects was -covered earlier in @ref{Moving objects}, which says that objects -positioned relative to the staff can be moved by overriding their -@code{staff-position} property, which is specified in half staff -spaces relative to the center line of the staff. So the following -override placed just before the first tied note would move the tie up -to 3.5 half staff spaces above the center line: - -@code{\once \override Tie #'staff-position = #3.5} - -This completes bar two, giving: - -@lilypond[quote,verbatim,ragged-right] -rhMusic = \relative c'' { - r2 c4.\( g8 | - \once \override Tie #'staff-position = #3.5 - bes1~ | - \bar "||" - \time 6/4 - bes2. r8 - % Start polyphonic section of four voices - << - {c,8[ d fis bes a] | } - \\ - {c,8~ c2 | } - \\ - {s8 d2 | } - \\ - {s4 fis4. | } - >> - g2.\) -} - -lhMusic = \relative c' { - r2 2( | - 1)\arpeggio | - r2. d,,4 r4 r | - r4 -} - -\score { - \new PianoStaff << - \new Staff = "RH" << - \key g \minor - \rhMusic - >> - \new Staff = "LH" << - \key g \minor - \clef "bass" - \lhMusic - >> - >> -} -@end lilypond - -On to bar three and the start of the Moderato section. The tutorial -showed how to add embolded text with the @code{\markup} command, so -adding @q{Moderato} in bold is easy. But how do we merge notes in -different voices together? This is where we need to turn to the -Notation Reference for help. A search for @qq{merge} in the Notation -Reference index quickly leads us to the commands for merging -differently headed and differently dotted notes in @ruser{Collision -resolution}. In our example we need to merge both types of note for -the duration of the polyphonic section in bar 3, so using the -information we find in the Notation Reference we add - -@example -\mergeDifferentlyHeadedOn -\mergeDifferentlyDottedOn -@end example - -@noindent -to the start of that section and - -@example -\mergeDifferentlyHeadedOff -\mergeDifferentlyDottedOff -@end example - -@noindent -to the end, giving: - -@lilypond[quote,verbatim,ragged-right] -rhMusic = \relative c'' { - r2 c4.\( g8 | - \once \override Tie #'staff-position = #3.5 - bes1~ | - \bar "||" - \time 6/4 - bes2.^\markup {\bold "Moderato"} r8 - \mergeDifferentlyHeadedOn - \mergeDifferentlyDottedOn - % Start polyphonic section of four voices - << - {c,8[ d fis bes a] | } - \\ - {c,8~ c2 | } - \\ - {s8 d2 | } - \\ - {s4 fis4. | } - >> - \mergeDifferentlyHeadedOff - \mergeDifferentlyDottedOff - g2.\) -} - -lhMusic = \relative c' { - r2 2( | - 1)\arpeggio | - r2. d,,4 r4 r | - r4 -} - -\score { - \new PianoStaff << - \new Staff = "RH" << - \key g \minor - \rhMusic - >> - \new Staff = "LH" << - \key g \minor - \clef "bass" - \lhMusic - >> - >> -} -@end lilypond - -These overrides have merged the two F-sharp notes, but not the two -on D. Why not? The answer is there in the same section in the -Notation Reference -- notes being merged must have stems in -opposite directions and two notes cannot be merged successfully if -there is a third note in the same note column. Here the two D's -both have upward stems and there is a third note -- the C. We know -how to change the stem direction using @code{\stemDown}, and -the Notation Reference also says how to move the C -- apply a shift -using one of the @code{\shift} commands. But which one? -The C is in voice two which has shift off, and the two D's are in -voices one and three, which have shift off and shift on, -respectively. So we have to shift the C a further level still -using @code{\shiftOnn} to avoid it interfering with the two D's. -Applying these changes gives: - -@cindex Tie, example of overriding -@cindex staff-position property, example - -@lilypond[quote,verbatim,ragged-right] -rhMusic = \relative c'' { - r2 c4.\( g8 | - \once \override Tie #'staff-position = #3.5 - bes1~ | - \bar "||" - \time 6/4 - bes2.^\markup {\bold "Moderato"} r8 - \mergeDifferentlyHeadedOn - \mergeDifferentlyDottedOn - % Start polyphonic section of four voices - << - {c,8[ d fis bes a] | } - \\ - % Move the c2 out of the main note column so the merge will work - {c,8~ \shiftOnn c2 | } - \\ - % Stem on the d2 must be down to permit merging - {s8 \stemDown d2 | } - \\ - {s4 fis4. | } - >> - \mergeDifferentlyHeadedOff - \mergeDifferentlyDottedOff - g2.\) -} - -lhMusic = \relative c' { - r2 2( | - 1)\arpeggio | - r2. d,,4 r4 r | - r4 -} - -\score { - \new PianoStaff << - \new Staff = "RH" << - \key g \minor - \rhMusic - >> - \new Staff = "LH" << - \key g \minor - \clef "bass" - \lhMusic - >> - >> -} -@end lilypond - -Nearly there. Only two problems remain: The downward stem on the -merged D should not be there, and the C would be better positioned -to the right of the D's. We know how to do both of these from the -earlier tweaks: we make the stem transparent, and move the C with -the @code{force-hshift} property. Here's the final result: - -@cindex NoteColumn, example of overriding -@cindex force-hshift property, example -@cindex Stem, example of overriding -@cindex transparent property, example - -@lilypond[quote,verbatim,ragged-right] -rhMusic = \relative c'' { - r2 - c4.\( g8 | - \once \override Tie #'staff-position = #3.5 - bes1~ | - \bar "||" - \time 6/4 - bes2.^\markup {\bold "Moderato"} r8 - \mergeDifferentlyHeadedOn - \mergeDifferentlyDottedOn - << - {c,8[ d fis bes a] | } - \\ - % Reposition the c2 to the right of the merged note - {c,8~ \once \override NoteColumn #'force-hshift = #1.0 - % Move the c2 out of the main note column so the merge will work - \shiftOnn c2} - \\ - % Stem on the d2 must be down to permit merging - {s8 \stemDown \once \override Stem #'transparent = ##t d2} - \\ - {s4 fis4.} - >> - \mergeDifferentlyHeadedOff - \mergeDifferentlyDottedOff - g2.\) -} - -lhMusic = \relative c' { - r2 2( | - 1)\arpeggio | - r2. d,,4 r4 r | - r4 -} - -\score { - \new PianoStaff << - \new Staff = "RH" << - \key g \minor - \rhMusic - >> - \new Staff = "LH" << - \key g \minor - \clef "bass" - \lhMusic - >> - >> -} -@end lilypond - - -@node Further tweaking -@section Further tweaking - -@menu -* Other uses for tweaks:: -* Using variables for tweaks:: -* Other sources of information:: -* Avoiding tweaks with slower processing:: -* Advanced tweaks with Scheme:: -@end menu - -@node Other uses for tweaks -@subsection Other uses for tweaks - -@cindex transparent property, use of -@cindex objects, making invisible -@cindex removing objects -@cindex objects, removing -@cindex hiding objects -@cindex objects, hiding -@cindex invisible objects -@cindex objects, invisible -@cindex tying notes across voices - -@subheading Tying notes across voices - -The following example demonstrates how to connect notes in -different voices using ties. Normally, only two notes in the -same voice can be connected with ties. By using two voices, -with the tied notes in one of them - -@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: - -@cindex Stem, example of overriding -@cindex transparent property, example - -@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 can 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 - -@subheading Simulating a fermata in MIDI - -@cindex stencil property, use of -@cindex fermata, implementing in MIDI - -For outside-staff objects it is usually better to override the -object's @code{stencil} property rather than its @code{transparent} -property when you wish to remove it from the printed output. -Setting the @code{stencil} property of an object to @code{#f} will -remove that object entirely from the printed output. This means it -has no effect on the placement of other objects placed relative to -it. - -For example, if we wished to change the metronome setting in order -to simulate a fermata in the MIDI output we would not want the -metronome markings to appear in the printed output, and we would -not want it to influence the spacing between the two systems or -the positions of adjacent annotations on the staff. So setting -its @code{stencil} property to @code{#f} would be the best way. -We show here the effect of the two methods: - -@cindex MetronomeMark, example of overriding -@cindex transparent property, example - -@lilypond[quote,verbatim,ragged-right] -\score { - \relative c'' { - % Visible tempo marking - \tempo 4=120 - a4 a a - \once \override Score.MetronomeMark #'transparent = ##t - % Invisible tempo marking to lengthen fermata in MIDI - \tempo 4=80 - a\fermata - % New tempo for next section - \tempo 4=100 - a a a a - } - \layout { } - \midi { } -} -@end lilypond - -@cindex MetronomeMark, example of overriding -@cindex stencil property, example - -@lilypond[quote,verbatim,ragged-right] -\score { - \relative c'' { - % Visible tempo marking - \tempo 4=120 - a4 a a - \once \override Score.MetronomeMark #'stencil = ##f - % Invisible tempo marking to lengthen fermata in MIDI - \tempo 4=80 - a\fermata - % New tempo for next section - \tempo 4=100 - a a a a - } - \layout { } - \midi { } -} -@end lilypond - -@noindent -Both methods remove the metronome mark which lengthens the fermata -from the printed output, and both affect the MIDI timing as -required, but the transparent metronome mark in the first line -forces the following tempo indication too high while the -second (with the stencil removed) does not. - -@node Using variables for tweaks -@subsection Using variables for tweaks - -@cindex variables, using for tweaks -@cindex using variables for tweaks -@cindex tweaks, using variables for - -Override commands are often long and tedious to type, and they -have to be absolutely correct. If the same overrides are to be -used many times it may be worth defining variables to hold them. - -Suppose we wish to emphasize certain words in lyrics by printing -them in bold italics. The @code{\italic} and @code{\bold} -commands only work within lyrics if they are embedded, together with -the word or words to be modified, within a @code{\markup} block, -which makes them tedious to enter. The need to embed the words -themselves prevents their use in simple variables. As an -alternative can we use @code{\override} and @code{\revert} commands? - -@example -@code{\override Lyrics . LyricText #'font-shape = #'italic} -@code{\override Lyrics . LyricText #'font-series = #'bold} - -@code{\revert Lyrics . LyricText #'font-shape} -@code{\revert Lyrics . LyricText #'font-series} -@end example - -These would also be extremely tedious to enter if there were many -words requiring emphasis. But we @emph{can} define these as two -variables and use those to bracket the words to be emphasized. -Another advantage of using variables for these overrides is that -the spaces around the dot are not necessary, since they are not -being interpreted in @code{\lyricmode} directly. Here's an example -of this, although in practice we would choose shorter names -for the variables to make them quicker to type: - -@cindex LyricText, example of overriding -@cindex font-shape property, example -@cindex font-series property, example - -@lilypond[quote,verbatim] -emphasize = { - \override Lyrics.LyricText #'font-shape = #'italic - \override Lyrics.LyricText #'font-series = #'bold -} -normal = { - \revert Lyrics.LyricText #'font-shape - \revert Lyrics.LyricText #'font-series -} - -global = { \time 4/4 \partial 4 \key c \major} -SopranoMusic = \relative c' { c4 | e4. e8 g4 g | a a g } -AltoMusic = \relative c' { c4 | c4. c8 e4 e | f f e } -TenorMusic = \relative c { e4 | g4. g8 c4. b8 | a8 b c d e4 } -BassMusic = \relative c { c4 | c4. c8 c4 c | f8 g a b c4 } -VerseOne = \lyrics { E -- | ter -- nal \emphasize Fa -- ther, \normal | strong to save, } -VerseTwo = \lyricmode { O | \emphasize Christ, \normal whose voice the | wa -- ters heard, } -VerseThree = \lyricmode { O | \emphasize Ho -- ly Spi -- rit, \normal | who didst brood } -VerseFour = \lyricmode { O | \emphasize Tri -- ni -- ty \normal of | love and pow'r } - -\score { - \new ChoirStaff << - \new Staff << - \clef "treble" - \new Voice = "Soprano" { \voiceOne \global \SopranoMusic } - \new Voice = "Alto" { \voiceTwo \AltoMusic } - \new Lyrics \lyricsto "Soprano" { \VerseOne } - \new Lyrics \lyricsto "Soprano" { \VerseTwo } - \new Lyrics \lyricsto "Soprano" { \VerseThree } - \new Lyrics \lyricsto "Soprano" { \VerseFour } - >> - \new Staff << - \clef "bass" - \new Voice = "Tenor" { \voiceOne \TenorMusic } - \new Voice = "Bass" { \voiceTwo \BassMusic } - >> - >> -} -@end lilypond - - - -@node Other sources of information -@subsection Other sources of information - -The Internals Reference documentation contains a lot of information -about LilyPond, but even more information can be gathered by -looking at the internal LilyPond files. To explore these, you must -first find the directory appropriate to your system. The location -of this directory depends (a) on whether you obtained LilyPond -by downloading a precompiled binary from lilypond.org -or whether you installed it from a package manager (i.e. -distributed with Linux, or installed under fink or cygwin) or -compiled it from source, and (b) on which operating system it is -being used: - -@strong{Downloaded from lilypond.org} - -@itemize @bullet -@item Linux - -Navigate to -@file{@var{INSTALLDIR}/lilypond/usr/share/lilypond/current/} - -@item MacOS X - -Navigate to -@file{@var{INSTALLDIR}/LilyPond.app/Contents/Resources/share/lilypond/current/} -by either @code{cd}-ing into this directory from the -Terminal, or control-clicking on the LilyPond application and -selecting @q{Show Package Contents}. - -@item Windows - -Using Windows Explorer, navigate to -@file{@var{INSTALLDIR}/LilyPond/usr/share/lilypond/current/} - -@end itemize - -@strong{Installed from a package manager or compiled from source} - -Navigate to -@file{@var{PREFIX}/share/lilypond/@var{X.Y.Z}/}, where -@var{PREFIX} is set by your package manager or @code{configure} -script, and @var{X.Y.Z} is the LilyPond version number. - -@smallspace - -Within this directory the two interesting subdirectories are - -@itemize -@item @file{ly/} - contains files in LilyPond format -@item @file{scm/} - contains files in Scheme format -@end itemize - -Let's begin by looking at some files in @file{ly/}. -Open @file{ly/property-init.ly} in a text editor. The one -you normally use for @code{.ly} files will be fine. This file -contains the definitions of all the standard LilyPond predefined -commands, such as @code{\stemUp} and @code{\slurDotted}. You will -see that these are nothing more than definitions of variables -containing one or a group of @code{\override} commands. For -example, @code{/tieDotted} is defined to be: - -@example -tieDotted = @{ - \override Tie #'dash-period = #0.75 - \override Tie #'dash-fraction = #0.1 -@} -@end example - -If you do not like the default values these predefined commands can -be redefined easily, just like any other variable, at the -head of your input file. - -The following are the most useful files to be found in -@file{ly/}: - -@multitable @columnfractions .4 .6 -@headitem Filename - @tab Contents -@item @file{ly/engraver-init.ly} - @tab Definitions of engraver Contexts -@item @file{ly/paper-defaults-init.ly} - @tab Specifications of paper-related defaults -@item @file{ly/performer-init.ly} - @tab Definitions of performer Contexts -@item @file{ly/property-init.ly} - @tab Definitions of all common predefined commands -@item @file{ly/spanner-init.ly} - @tab Definitions of spanner-related predefined commands -@end multitable - -Other settings (such as the definitions of markup commands) are -stored as @code{.scm} (Scheme) files. The Scheme programming -language is used to provide a programmable interface into -LilyPond internal operation. Further explanation of these files -is currently outside the scope of this manual, as a knowledge of -the Scheme language is required. Users should be warned that -a substantial amount of technical knowledge or time is required -to understand Scheme and these files (see @ref{Scheme tutorial}). - -If you have this knowledge, the Scheme files which may be of -interest are: - -@multitable @columnfractions .4 .6 -@headitem Filename - @tab Contents -@item @file{scm/auto-beam.scm} - @tab Sub-beaming defaults -@item @file{scm/define-grobs.scm} - @tab Default settings for grob properties -@item @file{scm/define-markup-commands.scm} - @tab Specify all markup commands -@item @file{scm/midi.scm} - @tab Default settings for MIDI output -@item @file{scm/output-lib.scm} - @tab Settings that affect appearance of frets, colors, - accidentals, bar lines, etc -@item @file{scm/parser-clef.scm} - @tab Definitions of supported clefs -@item @file{scm/script.scm} - @tab Default settings for articulations -@end multitable - - - -@node Avoiding tweaks with slower processing -@subsection Avoiding tweaks with slower processing - -LilyPond can perform extra checks while it processes input files. These -checks will take extra time to perform, but fewer manual tweaks -may be required to obtain an acceptable result. If a text script -or part of the lyrics extends over the margins these checks will -compress that line of the score just enough to fit within the -margins. - -To be effective under all circumstances these checks must be enabled -by placing the overrides in a Score @code{\with} block, rather than -in-line in music, as follows: - -@example -\new Score \with @{ - % Makes sure text scripts and lyrics are within the paper margins - \override PaperColumn #'keep-inside-line = ##t - \override NonMusicalPaperColumn #'keep-inside-line = ##t -@} @{ - .. -@} -@end example - -@node Advanced tweaks with Scheme -@subsection Advanced tweaks with Scheme - -Although many things are possible with the @code{\override} and -@code{\tweak} commands, an even more powerful way of modifying -the action of LilyPond is available through a programmable -interface to the LilyPond internal operation. Code written in -the Scheme programming language can be incorporated directly in -the internal operation of LilyPond. Of course, at least a basic -knowledge of programming in Scheme is required to do this, and an -introduction is provided in the @ref{Scheme tutorial}. - -As an illustration of one of the many possibilities, instead of -setting a property to a constant it can be set to a Scheme -procedure which is then called whenever that property is accessed -by LilyPond. The property can then be set dynamically to a value -determined by the procedure at the time it is called. In this -example we color the note head in accordance with its position on -the staff. - -@cindex x11-color function, example of using -@cindex NoteHead, example of overriding -@cindex color property, setting to Scheme procedure - -@lilypond[quote,verbatim,ragged-right] -#(define (color-notehead grob) - "Color the notehead according to its position on the staff." - (let ((mod-position (modulo (ly:grob-property grob 'staff-position) 7))) - (case mod-position - ;; Return rainbow colors - ((1) (x11-color 'red )) ; for C - ((2) (x11-color 'orange )) ; for D - ((3) (x11-color 'yellow )) ; for E - ((4) (x11-color 'green )) ; for F - ((5) (x11-color 'blue )) ; for G - ((6) (x11-color 'purple )) ; for A - ((0) (x11-color 'violet )) ; for B - ) - ) -) - -\relative c' { - % Arrange to obtain color from color-notehead procedure - \override NoteHead #'color = #color-notehead - c2 c' | - b4 g8 a b4 c | - c,2 a' | - g1 | -} -\addlyrics { - Some -- where o -- ver the Rain -- bow, way up high, -} -@end lilypond - -Further examples showing the use of these programmable interfaces -can be found in @ref{Tweaking with Scheme}. - - - - - - - - - - - - - - -