X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftweaks.itely;h=dc4de56f2a20bf7bc3b67b9f6974c87ef018aefc;hb=9e7b53f94e1e3bd7b3f7a14ba11a6cae6c8e9a73;hp=215d6c6aa0d1695e6a478aff9e32650d5abb1a9c;hpb=9755f17b5141ae25e1ad683c445a4505702f0b1f;p=lilypond.git diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely index 215d6c6aa0..7698e32f74 100644 --- a/Documentation/user/tweaks.itely +++ b/Documentation/user/tweaks.itely @@ -1,4 +1,12 @@ @c -*- coding: utf-8; mode: texinfo; -*- +@c This file is part of lilypond-learning.tely +@ignore + Translation of GIT committish: FILL-IN-HEAD-COMMITTISH + + When revising a translation, copy the HEAD committish of the + version that you are working on. See TRANSLATION for details. +@end ignore + @node Tweaking output @chapter Tweaking output @@ -7,195 +15,2080 @@ configurable; virtually every fragment of output may be changed. @menu -* Moving objects:: -* Fixing overlapping notation:: -* Common tweaks:: -* Default files:: -* Advanced tweaks with Scheme:: +* 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 -@node Moving objects -@section Moving objects +@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 Objects +@cindex Grobs +@cindex Spanners +@cindex Interfaces + +Tweaking involves modifying the internal operation and structures +of the LilyPond program, so we must first introduce some terms +which are used to describe those internal operations and +structures. + +The term @q{Object} is a generic term used to refer to the +multitude of internal structures built by LilyPond during the +processing of an input file. So when a command like @code{\new +Staff} is encountered a new object of type @code{Staff} is +constructed. That @code{Staff} object then holds all the +properties associated with that particular staff, for example, its +name and its key signature, together with details of the engravers +which have been assigned to operate within that staff's context. +Similarly, there are 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 specialised. Phrasing slurs, +crescendo hairpins, ottavo marks, and many other grobs are not +localised in a single place -- they have a starting point, an +ending point, and maybe other properties concerned with their +shape. Objects with an extended shape like these are called +@q{Spanners}. + +It remains to explain what @q{Interfaces} are. Many objects, +even though they are quite different, share common features +which need to be processed in the same way. +For example, all grobs have a color, a size, a position, etc, +and all these properties are processed in the same way during +LilyPond's +interpretation of the input file. To simplify these internal +operations these common actions and properties are grouped +together in an object called a @code{grob-interface}. There +are many other groupings of common properties like this, each +one given a name ending in @code{-interface}. In total there +are over 100 such interfaces. We shall see later why this is +of interest and use to the user. + +These, then, are the main terms relating to objects which we +shall use in this chapter. + +@node Naming conventions of objects and properties +@subsection Naming conventions of objects and properties + +We met some object naming conventions previously, in +@ref{Contexts and engravers}. Here for reference is a list +of the most common object and property types together with +the conventions for naming them and a couple of examples of +some real names. We have used A to stand for any capitalised +alphabetic character and 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 Example +@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 recognise the type of object from the names of its +properties. + + +@node Tweaking methods +@subsection Tweaking methods + +We have already met the commands @code{\set} and @code{\with}, +used to change the properties of @strong{contexts} and to remove +and add @strong{engravers}, in +@ref{Modifying context properties} and @ref{Adding +and removing engravers}. We now must meet one more command. + +The command to change the properties of @strong{layout objects} is +@code{\override}. Because this command has to modify +internal properties deep within LilyPond its syntax is not +as simple as the commands you have met so far. It needs to +know precisely which property of which object in which context +has to be modified, and what its new value is to be. Let's see +how this is done. + +The general syntax of this command is: + +@example +\override @emph{context}.@emph{layout_object} #'@emph{layout_property} = #@emph{value} +@end example + +@noindent +This will set the property with the name @emph{layout_property} +of the layout object with the name +@emph{layout_object}, which is a member of the @emph{context} +context, to the value @emph{value}. + +The @emph{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. + +For now, don't worry about the @code{#'}, which must precede the +layout property, and the @code{#}, which must precede the value. +These must always be present in exactly this form. This is the +most common command used in tweaking, and most of the rest of +this chapter will be directed to presenting examples of how it is +used. + +Once overridden, the property retains its new value until it is +overridden again or a @code{\revert} command is encountered. +The @code{\revert} command has the following syntax and causes +the value of the property to revert to its original default +value; note, not its previous value if several @code{\override} +commands have been issued. + +@example +\revert @emph{context}.@emph{layout_object} #'@emph{layout_property} +@end example + +Again, just like @emph{context} in the @code{\override} command, +@emph{context} is often not needed. It will be omitted +in many of the following examples. + +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 + +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. You may find the details in +@ruser{Objects connected to the input}. + +@node The Internals Reference manual +@section The Internals Reference manual + +@cindex Internals Reference + +@menu +* Properties of layout objects:: +* Properties found in interfaces:: +* 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 + +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 + +Let's use a concrete example with a simple fragment of real +music: + +@lilypond[quote,fragment,ragged-right,verbatim,relative=2] +{ + \time 6/8 + { + r4 b8 b[( g]) g | + g[( e]) e d[( f]) a | + a g + } + \addlyrics { + The man who feels love's sweet e -- mo -- tion + } +} +@end lilypond + +Suppose now that we decide we would like the slurs to be a +little heavier. Is this possible? The slur is certainly a +layout object, so the question is, @q{Is there a property +belonging to a slur which controls the heaviness?} To answer +this we must look in the Internals Reference, or IR for short. + +The IR for the version of LilyPond you are using may be found +on the LilyPond website at @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 often it is easier to go +straight to the IR and search there.) + +This Slur page in the IR tells us first that Slur objects are +created by the +Slur_engraver. Then it lists the standard settings. Note +these are @strong{not} in alphabetic order. Browse down +them looking for a property that might control the heaviness +of slurs, and you should find + +@example +@code{thickness} (number) + @code{1.2} + Line thickness, generally measured in @code{line-thickness} +@end example + +This 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 and @code{#} preceding the new value! + +The final question is, @q{Where should this command be +placed?} While you are unsure and learning, the best +answer is, @q{Within the music, before the first slur and +close to it.} Let's do that: + +@lilypond[quote,fragment,ragged-right,verbatim,relative=2] +{ + \time 6/8 + { + % Increase thickness of all following slurs from 1.2 to 5.0 + \override 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 + +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 + +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: + +@lilypond[quote,fragment,ragged-right,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 @code{\set} +and @code{\unset}, and before the command to be introduced +in the following section -- @code{revert}. + +@subheading Reverting -This may come as a surprise, but LilyPond is not perfect. Some notation -elements can overlap. This is unfortunate, but (in most cases) is easily -solved. +@cindex revert +@cindex default properties, reverting +@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: + +@lilypond[quote,fragment,ragged-right,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: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] -e4^\markup{ \italic ritenuto } g b e +{ + \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 -@cindex padding +@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 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 (in the html versions +of the IR) interfaces which LyricText supports. The list has +seven 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 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 diferently 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 special names which are known internally to +LilyPond. Some of them are the names of properties, +like @code{thickness} or @code{font-shape}, others are in +effect special values that can be given to properties, like +@code{italic}. Note the distinction from arbitary +text strings, which would appear as @code{"a text string"}. + +Ok, so the @code{\override} command we need to print the lyrics +in italics should be -The easiest solution is to increase the distance between the object -(in this case text, but it could easily be fingerings or dynamics -instead) and the note. In LilyPond, this is called the -@code{padding} property; it is measured in staff spaces. For most -objects, this value is around 1.0 or less (it varies with each -object). We want to increase it, so let's try 1.5 +@example + \override LyricText #'font-shape = #'italic +@end example + +@noindent +and this should be placed just in front of and close to the +lyrics which it should affect, like this: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\once \override TextScript #'padding = #1.5 -e4^\markup{ \italic ritenuto } g b e +{ + \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 -That looks better, but it isn't quite big enough. After experimenting -with a few values, we think 2.3 is the best number in this case. However, -this number is merely the result of experimentation and my personal -taste in notation. Try the above example with 2.3... but also try higher -(and lower) numbers. Which do you think looks the best? +@noindent +and the lyrics are all printed in italics. + +@subheading Specifying context in lyric mode +@cindex context, specifying in lyric mode + +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 recognise them. So the command should be: -The @code{staff-padding} property is closely related. @code{padding} -controls the minimum amount of space between an object and the nearest -other object (generally the note or the staff lines); -@code{staff-padding} controls the minimum amount of space between an -object and the staff. This is a subtle difference, but you can see -the behavior here. +@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.} + +@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 + @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 bracketed set of items separated by spaces, +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 brackets and preceded +by a hash sign, @code{#}. + @tab @code{#(#t #t #f)} +@end multitable + +@node Appearance of objects +@section Appearance of objects + +Let us now put what we have learnt 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 are commonly required +together -- if one of them is required for an object, so are +the others. Some objects then need the properties in some +interfaces, others need them from other interfaces. The +interfaces which contain the properties required 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}: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] -c4^"piu mosso" b a b -\once \override TextScript #'padding = #2.6 -c4^"piu mosso" d e f -\once \override TextScript #'staff-padding = #2.6 -c4^"piu mosso" fis a g -\break -c'4^"piu mosso" b a b -\once \override TextScript #'padding = #2.6 -c4^"piu mosso" d e f -\once \override TextScript #'staff-padding = #2.6 -c4^"piu mosso" fis a g -@end lilypond - -@cindex extra-offset - -Another solution gives us complete control over placing the object -- we -can move it horizontally or vertically. This is done with the -@code{extra-offset} property. It is slightly more complicated and can -cause other problems. When we move objects with @code{extra-offset}, -the movement is done after LilyPond has placed all other objects. This -means -that the result can overlap with other objects. +{ + \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 wrongly, 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: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\once \override TextScript #'extra-offset = #'( 1.0 . -1.0 ) -e4^\markup{ \italic ritenuto } g b e +{ + \time 12/16 + \override Staff.BarLine #'stencil = ##f + c4 b8 c d16 c d8 | + g, a16 b8 c d4 e16 | + e8 +} @end lilypond -With @code{extra-offset}, the first number controls the horizontal -movement (left is negative); the second number controls the vertical -movement (up is positive). After a bit of experimenting, we decided -that these values look good +Now the bar lines have vanished. + +@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 two hash signs before the opening bracket. +One is required as part of the value to introduce a vector, +and one is required, as always, to precede the value itself in +the @code{\override} command. + +@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 + +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: + +@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: @lilypond[quote,fragment,ragged-right,verbatim,relative=2] -\once \override TextScript #'extra-offset = #'( -1.6 . 1.0 ) -e4^\markup{ \italic ritenuto } g b e +{ + \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 we could make the bar lines invisible by coloring +them white. 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} colours listed in the first table in +@ruser{List of colors}. To set the bar lines to white +we write: + +@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 -Again, these numbers are simply the result of a few experiments and -looking at the output. You might prefer the text to be slightly higher, -or to the left, or whatever. Try it and look at the result! +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 + +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: + +@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 -One final warning: in this section, we used +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)}: + +@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: + +@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 + +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}. + +@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: + +@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 overrrides 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 synchronised 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 + +@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 -\once \override TextScript @dots{} +\override NoteHead #'font-size = #-2 @end example -This tweaks the display of text for the next note. If the note has -no text, this tweak does nothing (and does @strong{not} wait until -the next bit of text). To change the behavior of everything after -the command, omit the @code{\once}. To stop this tweak, use a -@code{\revert}. This is explained in depth in -@ref{The \override command}. +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}). -@lilypond[quote,fragment,ragged-right,verbatim,relative=3] -c4^"piu mosso" b -\once \override TextScript #'padding = #2.6 - a4 b -c4^"piu mosso" d e f -\once \override TextScript #'padding = #2.6 -c4^"piu mosso" d e f -c4^"piu mosso" d e f -\break -\override TextScript #'padding = #2.6 -c4^"piu mosso" d e f -c4^"piu mosso" d e f -\revert TextScript #'padding -c4^"piu mosso" d e f +@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: + +@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 -@seealso +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. -This manual: @ref{The \override command}, @ref{Common tweaks}. +@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: -@node Fixing overlapping notation -@section Fixing overlapping notation +@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 synchronised +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 behaviour:: +* Within-staff objects:: +* Outside staff objects:: +@end menu + + +@node Automatic behaviour +@subsection Automatic behaviour + +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 behaviour, 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 explicity set). Note that @q{Text3} +is automatically positioned close to the staff again, nestling +under @q{Text2}. + +@lilypond[quote,fragment,ragged-right,verbatim,relative=2] +c2^"Text1" +c^"Text2" +c^"Text3" +c^"Text4" +@end lilypond -In @ref{Moving objects}, we saw how to move a @code{TextScript} -object. The same mechanism can be used to move other types of -objects; simply replace @code{TextScript} with the name of -another object. +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 +behaviour. This can be done for whole sections of music or even +for an individual note. The property which controls this +behaviour 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. + +The following example shows in bar 1 the default behaviour 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 behaviour. + +@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 .2 .4 +@headitem Down/Left + @tab Up/Right + @tab Revert + @tab Effect +@item @code{\arpeggioDown} + @tab @code{\arpeggioUp} + @tab @code{\arpeggioNeutral} + @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 -To find the object name, look at the ``@strong{see also}'' at -bottom of the relevant documentation page. For example, at -the bottom of @ref{Dynamics}, we see +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. -@quotation -@seealso +@subheading Fingering +@cindex fingering, placement -Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}. -Vertical positioning of these symbols is handled by -@internalsref{DynamicLineSpanner}. -@end quotation +The placement of fingering is also affected by the value +of its @code{direction} property, but 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 fingering, +the first bar shows the default, then the effect of specifying +@code{DOWN} and @code{UP}: + +@lilypond[quote,fragment,ragged-right,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 + +This is how to control fingering on single notes, but the +@code{direction} +property is ignored for chords. Instead, by default, the +fingering is automatically placed both above and below the +notes of a chord, as shown: + +@lilypond[quote,fragment,ragged-right,verbatim,relative=2] + + + +@end lilypond + +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 +contraints 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. + +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: + +@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 +@funindex \startTextSpan +@funindex \stopTextSpan +@cindex ottava bracket + +@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 +#(set-octavation 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 +#(set-octavation 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. + +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} does 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: + +@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 +#(set-octavation 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 +#(set-octavation 0) +c, c c c +@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 behaviour, above (see @ref{Automatic behaviour}). +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: + +@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 + +@funindex \textLengthOn +@cindex notes, spreading out with text + +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 behaviour, 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 behaviour 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}. + +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. + +@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 honoured +c''2 +@end lilypond + + +@subheading Dynamics + +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 -So to move dynamics around vertically, we use +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 +@cindex @code{X-offset} +@cindex @code{Y-offset} +@cindex @code{X-extent} +@cindex @code{Y-extent} + +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 DynamicLineSpanner #'padding = #2.0 +\override DynamicText #'extra-spacing-width = #'(0 . 0) @end example -We cannot list every object, but here is a list of the most -common objects. +@noindent +Let's see if this works in our previous 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: + +@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 + +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 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 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. Because +accidentals are always positioned after and to the left of +note heads only the @code{right-padding} property has any effect. + +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 honour both +numbers. For example, the @code{Accidental} object only takes +notice of the first (left edge) number. + +@item +@code{staff-position} -@multitable @columnfractions .33 .66 +@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 occuring 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 + +Objects do not all have all of these properties in general. +It is necessary to go to the IR to look up which properties +are available for the object in question. + +@item +Finally, when all else fails, objects may be manually repositioned +relative to the staff center line verically, 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 + +Objects do not all have all of these properties in general. +It is necessary to go to the IR to look up which properties +are available for the object in question. + +@end enumerate + +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 Ties @tab @code{Tie} -@item Slurs @tab @code{Slur} -@item Articulations @tab @code{Script} @item Fingerings @tab @code{Fingering} -@item Text e.g. @code{^"text"} @tab @code{TextScript} @item Rehearsal / Text marks @tab @code{RehearsalMark} +@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 Common tweaks -@section Common tweaks - -Some overrides are so common that predefined commands are provided as -short-cuts, such as @code{\slurUp} and @code{\stemDown}. These -commands are described in the Notation Reference under the appropriate -sections. - -The complete list of modifications available for each type of -object (like slurs or beams) are documented in the Program -Reference. However, many layout objects share properties which can be -used to apply generic tweaks. +@node Fixing overlapping notation +@subsection Fixing overlapping notation -@itemize @bullet +Let's now see how the properties in the previous section can +help to resolve overlapping notation. -@cindex padding +@c FIXME: formatting +@subheading @code{padding} +@cindex padding property -@item The @code{padding} property can be set to increase (or decrease) the distance between symbols that are printed -above or below notes. This applies to all objects with -@code{side-position-interface}. +above or below notes. @lilypond[quote,fragment,relative=1,verbatim] c2\fermata @@ -215,21 +2108,101 @@ 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 +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 -@ref{Constructing a tweak}. +@ruser{Constructing a tweak}. -@cindex extra-offset +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. + -@item -The @code{extra-offset} property moves objects around -in the output; it requires a pair of numbers. The first number -controls horizontal movement; a positive number will -move the object to the right. The second number controls vertical -movement; a positive number will move it higher. The -@code{extra-offset} property is a low-level feature: the -formatting engine is completely oblivious to these offsets. +@subheading @code{left-padding} and @code{right-padding} +@cindex left-padding property +@cindex right-padding property + +TODO Example showing the utility of these properties -td + +@subheading staff-padding property +@cindex staff-padding property + +@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: + +@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 +@cindex 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: + +@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 staff-position property + +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}. + +@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 extra-offset property + +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: @@ -242,16 +2215,594 @@ f-5 f-5 @end lilypond - @item -Setting the @code{transparent} property will cause an object to be printed -in `invisible ink': the object is not printed, but all its other -behavior is retained. The object still takes up space, it takes part in -collisions, and slurs, ties, and beams can be attached to it. -@cindex transparent objects +@subheading force-hshift property +@cindex 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: + +@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 + + +@subheading positions property +@cindex positions property + +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. + +@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 only 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: + +@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. + +@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 +@lilypond[quote,ragged-right] +rhMusic = \relative c'' { + r2 + c4.\( g8 | + \once \override Tie #'staff-position = #3.5 + bes1~ | + \bar "||" + \time 6/4 + \override Staff.NoteCollision #'merge-differently-headed = ##t + \override Staff.NoteCollision #'merge-differently-dotted = ##t + 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.} + >> + \revert Staff.NoteCollision #'merge-differently-headed + \revert Staff.NoteCollision #'merge-differently-dotted + 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? The +index in the Notation Reference does not mention merging, +but a search of the text for @q{merge} quickly leads us to +the overrides 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 +in the Notation Reference we add + +@example +\override Staff.NoteCollision #'merge-differently-headed = ##t +\override Staff.NoteCollision #'merge-differently-dotted = ##t +@end example + +@noindent +to the start of that section and + +@example +\revert Staff.NoteCollision #'merge-differently-headed +\revert Staff.NoteCollision #'merge-differently-dotted +@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 + \override Staff.NoteCollision #'merge-differently-headed = ##t + \override Staff.NoteCollision #'merge-differently-dotted = ##t + % Start polyphonic section of four voices + << + {c,8[ d fis bes a] | } + \\ + {c,8~ c2 | } + \\ + {s8 d2 | } + \\ + {s4 fis4. | } + >> + \revert Staff.NoteCollision #'merge-differently-headed + \revert Staff.NoteCollision #'merge-differently-dotted + 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 interferring with the two D's. +Applying these changes gives: + +@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 + \override Staff.NoteCollision #'merge-differently-headed = ##t + \override Staff.NoteCollision #'merge-differently-dotted = ##t + % 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. | } + >> + \revert Staff.NoteCollision #'merge-differently-headed + \revert Staff.NoteCollision #'merge-differently-dotted + 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: + +@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 + \override Staff.NoteCollision #'merge-differently-headed = ##t + \override Staff.NoteCollision #'merge-differently-dotted = ##t + << + {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.} + >> + \revert Staff.NoteCollision #'merge-differently-headed + \revert Staff.NoteCollision #'merge-differently-dotted + 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:: +* Advanced tweaks with Scheme:: +* Avoiding tweaks with slower processing:: +@end menu + +@node Other uses for tweaks +@subsection Other uses for tweaks + +@itemize + +@cindex transparent property +@cindex objects, making invisible @cindex removing objects +@cindex objects, removing @cindex hiding objects @cindex invisible objects + +@item +Setting the @code{transparent} property will cause an object +to be printed in @q{invisible ink}: the object is not printed, +but all its other behavior is retained. The object still takes +up space, it takes part in collisions, and slurs, ties, and beams +can be attached to it. + The following example demonstrates how to connect different voices using ties. Normally, ties only connect two notes in the same voice. By introducing a tie in a different voice, @@ -277,25 +2828,80 @@ voices: } >> @end lilypond -@end itemize +To make sure that the just-blanked stem doesn't squeeze the tie too much, +we also lengthen the stem, by setting the @code{length} to +@code{8}, -@cindex Tweaks, distances -@cindex Distances +@lilypond[quote,fragment,relative=2,verbatim] +<< { + \once \override Stem #'transparent = ##t + \once \override Stem #'length = #8 + b8~ b8\noBeam +} \\ { + b[ g8] +} >> +@end lilypond + +@cindex stencil property + +@item +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 marking to appear in the printed output, and we would +not want it to influence the spacing between the two systems or +the spacing of the notes 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: + +@lilypond[quote,verbatim] +\score { + \relative c'' { + % Visible tempo marking + \tempo 4=120 + a4 a a + \once \override Score.MetronomeMark #'transparent = ##t + % Invisible tempo marking to lengthen fermata note in MIDI + \tempo 4=80 + a\fermata + \once \override Score.MetronomeMark #'stencil = ##f + % Invisible tempo marking to restore tempo in MIDI + \tempo 4=120 + a a a a + } + \midi { } +} +@end lilypond + +@noindent +Both methods remove the metronome mark from the printed output, +and both affect the MIDI timing as required, but the first +(transparent) metronome mark still influences the note spacing +while the second (with no stencil) does not. + +@end itemize -Distances in LilyPond are measured in staff-spaces, while most -thickness properties are measured in line-thickness. Some -properties are different; for example, the thickness of beams -are measured in staff-spaces. For more information, see the -relevant portion of the program reference. +@node Using variables for tweaks +@subsection Using variables for tweaks +TODO Add section -@node Default files -@section Default files +@node Other sources of information +@subsection Other sources of information -The Program Reference documentation contains a lot of information +The Internals Reference documentation contains a lot of information about LilyPond, but even more information can be gathered from looking at the internal LilyPond files. +TODO Show example, then explain where to find ly/propert-ly. + Some default settings (such as the definitions for @code{\header@{@}}s) are stored as @code{.ly} files. Other settings (such as the definitions of markup commands) are @@ -304,17 +2910,17 @@ outside the scope of this manual; users should be warned that a substantial amount of technical knowledge or time is required to understand these files. -@itemize @bullet +@itemize -@item Linux: @file{@{INSTALLDIR@}/lilypond/usr/share/lilypond/current/} +@item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/} @item OSX: -@file{@{INSTALLDIR@}/LilyPond.app/Contents/Resources/share/lilypond/current/}. -To access this, either @code{cd} into this directory from -the Terminal, or control-click on the LilyPond application -and select "Show Package Contents". +@file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}. +To access this, either @code{cd} into this directory from the +Terminal, or control-click on the LilyPond application and select +@q{Show Package Contents}. -@item Windows: @file{@{INSTALLDIR@}/LilyPond/usr/share/lilypond/current/} +@item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/} @end itemize @@ -324,17 +2930,19 @@ particular interest. Files such as @file{ly/property-init.ly} and @node Advanced tweaks with Scheme -@section Advanced tweaks with Scheme +@subsection Advanced tweaks with Scheme We have seen how LilyPond output can be heavily modified using commands like @code{\override TextScript #'extra-offset = ( 1 . -1)}. But we have even more power if we use Scheme. For a full explantion -of this, see the @ref{Scheme tutorial} and -@ref{Interfaces for programmers}. +of this, see the @ref{Scheme tutorial}, and +@ruser{Interfaces for programmers}. We can use Scheme to simply @code{\override} commands, +TODO Check this is a valid example with skylining + @lilypond[quote,verbatim,ragged-right] padText = #(define-music-function (parser location padding) (number?) #{ @@ -352,19 +2960,21 @@ padText = #(define-music-function (parser location padding) (number?) We can use it to create new commands, +TODO Check this is a valid example with skylining + @lilypond[quote,verbatim,ragged-right] tempoMark = #(define-music-function (parser location padding marktext) (number? string?) #{ \once \override Score . RehearsalMark #'padding = $padding - \once \override Score . RehearsalMark #'no-spacing-rods = ##t + \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0) \mark \markup { \bold $marktext } #}) \relative c'' { -c2 e -\tempoMark #3.0 #"Allegro" -g c + c2 e + \tempoMark #3.0 #"Allegro" + g c } @end lilypond @@ -382,3 +2992,45 @@ pattern = #(define-music-function (parser location x y) (ly:music? ly:music?) } @end lilypond + +@node Avoiding tweaks with slower processing +@subsection Avoiding tweaks with slower processing + +LilyPond can perform extra checks while it processes files. These +commands will take extra time, but the result may require fewer +manual tweaks. + +@example +%% makes sure text scripts and lyrics are within the paper margins +\override Score.PaperColumn #'keep-inside-line = ##t +\override Score.NonMusicalPaperColumn #'keep-inside-line = ##t +@end example + +In some cases (see issue 246), this must be done before +@code{\override} commands can be processed. + +@verbatim +\new Score \with { + \override PaperColumn #'keep-inside-line = ##t + \override NonMusicalPaperColumn #'keep-inside-line = ##t + } { + .. +} +@end verbatim + + + + + + + + + + + + + + + + +