@c -*- coding: utf-8; mode: texinfo; -*-
-@c This file is part of lilypond.tely
+@c This file is part of lilypond-learning.tely
@ignore
Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
@menu
-* Moving objects::
-* Fixing overlapping notation::
-* Common tweaks::
-* Default files::
-* Fitting music onto fewer pages::
-* Advanced tweaks with Scheme::
-* Avoiding tweaks with slower processing::
+* 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
+
+@cindex revert
+@cindex default properties, reverting
+@funindex \revert
-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.
+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]
-e4^\markup{ \italic ritenuto } g b e
+{
+ \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]
+{
+ \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
+
+@example
+ \override LyricText #'font-shape = #'italic
+@end example
-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
+@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]
+{
+ \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]
+{
+ \time 12/16
+ \override Staff.BarLine #'stencil = ##f
+ c4 b8 c d16 c d8 |
+ g, a16 b8 c d4 e16 |
+ e8
+}
+@end lilypond
+
+Now the bar lines have vanished.
+
+@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]
+{
+ \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
+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
+
+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]
-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 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]
-\once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
-e4^\markup{ \italic ritenuto } g b e
+\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
-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
+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]
-\once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
-e4^\markup{ \italic ritenuto } g b e
+\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
-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!
+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
-One final warning: in this section, we used
+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.
+
+@node Length and thickness of objects
+@subsection Length and thickness of objects
-This manual: @ref{The \override command}, @ref{Common tweaks}.
+@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:
+
+@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
-@node Fixing overlapping notation
-@section Fixing overlapping notation
+@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
+
+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
-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.
+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.
-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
+@subheading Fingering
+@cindex fingering, placement
-@quotation
-@seealso
+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.
-Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
-Vertical positioning of these symbols is handled by
-@internalsref{DynamicLineSpanner}.
-@end quotation
+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]
+<c-5 g-3>
+<c-5 g-3 e-2>
+<c-5 g-3 e-2 c-1>
+@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)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(left)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(up left down)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(up left)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(right)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+@end lilypond
@noindent
-So to move dynamics around vertically, we use
+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)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(left)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(up left down)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(up left)
+<f-2>
+< c-1 e-2 g-3 b-5 > 4
+\set fingeringOrientations = #'(right)
+<f-2>
+< 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
+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}
+
+@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.
-@multitable @columnfractions .33 .66
+@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
@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:
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
+ <ees c>2
+ des2
+ }
+ >> |
+ <c ees aes c>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 <ees c>2
+ \once \override NoteColumn #'force-hshift = #0.5 des2
+ }
+ >> |
+ <c ees aes c>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 <c g ees>2( |
+ <d g, d>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 <c g ees>2 |
+ <d g, d>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 <c g ees>2( |
+ <d g, d>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 <c g ees>2( |
+ <d g, d>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 <c g ees>2( |
+ <d g, d>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 <c g ees>2( |
+ <d g, d>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 <c g ees>2( |
+ <d g, d>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,
and blanking the first up-stem in that voice, the tie appears to cross
voices:
-
@lilypond[quote,fragment,relative=2,verbatim]
<< {
\once \override Stem #'transparent = ##t
} >>
@end lilypond
-To make sure that the just blanked stem doesn't sqeeuze the too much
-tie, we also lengthen the stem, by setting the @code{length} to
+To make sure that the just-blanked stem doesn't squeeze the tie too much,
+we also lengthen the stem, by setting the @code{length} to
@code{8},
@lilypond[quote,fragment,relative=2,verbatim]
} >>
@end lilypond
-@end itemize
+@cindex stencil property
-@cindex Tweaks, distances
-@cindex Distances
+@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
a substantial amount of technical knowledge or time is required
to understand these files.
-@itemize @bullet
+@itemize
@item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
@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
-"Show Package Contents".
+@q{Show Package Contents}.
@item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
@file{ly/declarations-init.ly} define all the common tweaks.
-@node Fitting music onto fewer pages
-@section Fitting music onto fewer pages
-
-Sometimes you can end up with one or two staves on a second
-(or third, or fourth...) page. This is annoying, especially
-if you look at previous pages and it looks like there is plenty
-of room left on those.
-
-When investigating layout issues, @code{annotate-spacing} is
-an invaluable tool. This command prints the values of various
-layout spacing commands; see @ref{Displaying spacing} for more
-details. From the output of @code{annotate-spacing}, we can
-see which margins we may wish to alter.
-
-Other than margins, there are a few other options to save space:
-
-@itemize
-@item
-You may tell LilyPond to place systems as close together as
-possible (to fit as many systems as possible onto a page), but
-then to space those systems out so that there is no blank
-space at the bottom of the page.
-
-@example
-\paper @{
-between-system-padding = #0.1
-between-system-space = #0.1
-ragged-last-bottom = ##f
-ragged-bottom = ##f
-@}
-@end example
-
-@item
-You may force the number of systems (i.e., if LilyPond wants
-to typeset some music with 11 systems, you could force it to
-use 10).
-
-@example
-\paper @{
-system-count = #10
-@}
-@end example
-
-@item
-Avoid (or reduce) objects which increase the vertical size of
-a system. For example, volta repeats (or alternate repeats)
-require extra space. If these repeats are spread over two
-systems, they will take up more space than one system with
-the volta repeats and another system without.
-
-Another example is moving dynamics which ``stick out'' of
-a system.
-
-@lilypond[verbatim,quote,fragment]
-\relative c' {
- e4 c g\f c
- \override DynamicLineSpanner #'padding = #-1.8
- \override DynamicText #'extra-offset = #'( -2.1 . 0)
- e4 c g\f c
-}
-@end lilypond
-
-@item
-Alter the horizontal spacing via @code{SpacingSpanner}. See
-@ref{Changing horizontal spacing} for more details.
-
-@lilypond[verbatim,quote]
-\score {
- \relative c'' {
- g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
- g4 e e2 | f4 d d2 | c4 e g g | c,1 |
- d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
- g4 e e2 | f4 d d2 | c4 e g g | c,1 |
- }
- \layout {
- \context {
- \Score
- \override SpacingSpanner
- #'base-shortest-duration = #(ly:make-moment 1 4)
- }
- }
-}
-@end lilypond
-
-@end itemize
-
-
@node 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?)
#{
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?)
#})
\relative c'' {
-c2 e
-\tempoMark #3.0 #"Allegro"
-g c
+ c2 e
+ \tempoMark #3.0 #"Allegro"
+ g c
}
@end lilypond
@node Avoiding tweaks with slower processing
-@section 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
@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
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
projects / lilypond.git / blobdiff