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