X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Flearning%2Ftweaks.itely;fp=Documentation%2Flearning%2Ftweaks.itely;h=40f46cf6759762ad27da16ba89e1b801480b44e8;hb=941dff9d2a67080e0dd8474f1e70f0c72ace6424;hp=0000000000000000000000000000000000000000;hpb=5a22d6233a39d3164e1ca043244794c268be4ad0;p=lilypond.git

diff --git a/Documentation/learning/tweaks.itely b/Documentation/learning/tweaks.itely
new file mode 100644
index 0000000000..40f46cf675
--- /dev/null
+++ b/Documentation/learning/tweaks.itely
@@ -0,0 +1,4165 @@
+@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}.
+
+
+