+@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 potted commands which can
+simply be copied to obtain the same effect in your own scores, and
+at the same time we show how these commands may be constructed so
+that you may learn how to develop your own tweaks.
+
+Before starting on this Chapter you may wish to review the section
+@ref{Contexts and engravers}, as Contexts, Engravers, and the
+Properties contained within them are fundamental to understanding
+and constructing Tweaks.
+
+@node Objects and interfaces
+@subsection Objects and interfaces
+
+@cindex Objects
+@cindex Grobs
+@cindex Spanners
+@cindex Interfaces
+
+Tweaking involves modifying the internal operation and structures
+of the LilyPond program, so we must first introduce some terms
+which are used to describe those internal operations and
+structures.
+
+The term @q{Object} is a generic term used to refer to the
+multitude of internal structures built by LilyPond during the
+processing of an input file. So when a command like @code{\new
+Staff} is encountered a new object of type @code{Staff} is
+constructed. That @code{Staff} object then holds all the
+properties associated with that particular staff, for example, its
+name and its key signature, together with details of the engravers
+which have been assigned to operate within that staff's context.
+Similarly, there are @code{Voice} objects, @code{Score} objects,
+@code{Lyric} objects, and objects to represent bar lines,
+ note heads, ties, dynamics, etc, each with their own set of
+properties.
+
+Some types of object are given special names. Objects which
+represent items of notation on the printed output such as
+ note heads, stems, slurs, ties, fingering, clefs, etc are called
+@q{Layout objects}, often known as @q{Graphical Objects}, or
+@q{Grobs} for short. These are still objects in the generic sense
+above, and so they too all have properties associated with them,
+such as their position, size, color, etc.
+
+Some layout objects are still more specialised. Phrasing slurs,
+crescendo hairpins, ottavo marks, and many other grobs are not
+localised in a single place -- they have a starting point, an
+ending point, and maybe other properties concerned with their
+shape. Objects with an extended shape like these are called
+@q{Spanners}.
+
+It remains to explain what @q{Interfaces} are. Many objects,
+even though they are quite different, share common features
+which need to be processed in the same way.
+For example, all grobs have a color, a size, a position, etc,
+and all these properties are processed in the same way during
+LilyPond's
+interpretation of the input file. To simplify these internal
+operations these common actions and properties are grouped
+together in an object called a @code{grob-interface}. There
+are many other groupings of common properties like this, each
+one given a name ending in @code{-interface}. In total there
+are over 100 such interfaces. We shall see later why this is
+of interest and use to the user.
+
+These, then, are the main terms relating to objects which we
+shall use in this chapter.
+
+@node Naming conventions of objects and properties
+@subsection Naming conventions of objects and properties
+
+We met some object naming conventions previously, in
+@ref{Contexts and engravers}. Here for reference is a list
+of the most common object and property types together with
+the conventions for naming them and a couple of examples of
+some real names. We have used A to stand for any capitalised
+alphabetic character and aaa to stand for any number of
+lower-case alphabetic characters. Other characters are used
+verbatim.
+
+@multitable @columnfractions .33 .33 .33
+@headitem Object/property type
+ @tab Naming convention
+ @tab Example
+@item Contexts, Layout Objects
+ @tab Aaaa or AaaaAaaaAaaa
+ @tab Staff, GrandStaff,
+@item Engravers
+ @tab Aaaa_aaa_engraver
+ @tab Clef_engraver, Note_heads_engraver
+@item Interfaces
+ @tab aaa-aaa-interface
+ @tab grob-interface, break-aligned-interface
+@item Context Properties
+ @tab aaa or aaaAaaaAaaa
+ @tab alignAboveContext, skipBars
+@item Layout Object Properties
+ @tab aaa or aaa-aaa-aaa
+ @tab direction, beam-thickness
+@end multitable
+
+As we shall see shortly, the properties of different types of
+object are modified by different commands, so it is useful to
+be able to recognise the type of object from the names of its
+properties.
+
+
+@node Tweaking methods
+@subsection Tweaking methods
+
+We have already met the commands @code{\set} and @code{\with},
+used to change the properties of @strong{contexts} and to remove
+and add @strong{engravers}, in
+@ref{Modifying context properties} and @ref{Adding
+and removing engravers}. We now must meet one more command.
+
+The command to change the properties of @strong{layout objects} is
+@code{\override}. Because this command has to modify
+internal properties deep within LilyPond its syntax is not
+as simple as the commands you have met so far. It needs to
+know precisely which property of which object in which context
+has to be modified, and what its new value is to be. Let's see
+how this is done.
+
+The general syntax of this command is:
+
+@example
+\override @emph{context}.@emph{layout_object} #'@emph{layout_property} = #@emph{value}
+@end example
+
+@noindent
+This will set the property with the name @emph{layout_property}
+of the layout object with the name
+@emph{layout_object}, which is a member of the @emph{context}
+context, to the value @emph{value}.
+
+The @emph{context} can be omitted (and usually is) when the
+required context is unambiguously implied and is one of lowest
+level contexts, i.e., @code{Voice}, @code{ChordNames} or
+@code{Lyrics}, and we shall omit it in many of the following
+examples. We shall see later when it must be specified.
+
+For now, don't worry about the @code{#'}, which must precede the
+layout property, and the @code{#}, which must precede the value.
+These must always be present in exactly this form. This is the
+most common command used in tweaking, and most of the rest of
+this chapter will be directed to presenting examples of how it is
+used.
+
+Once overridden, the property retains its new value until it is
+overridden again or a @code{\revert} command is encountered.
+The @code{\revert} command has the following syntax and causes
+the value of the property to revert to its original default
+value; note, not its previous value if several @code{\override}
+commands have been issued.
+
+@example
+\revert @emph{context}.@emph{layout_object} #'@emph{layout_property}
+@end example
+
+Again, just like @emph{context} in the @code{\override} command,
+@emph{context} is often not needed. It will be omitted
+in many of the following examples.
+
+There is another form of the override command,
+@code{\overrideProperty}, which is occasionally required.
+We mention it here for completeness, but for details see
+@ruser{Difficult tweaks}.
+@c Maybe explain in a later iteration -td
+
+The final tweaking command which is available is @code{\tweak}.
+It is not really a new command but a shorthand for an
+@code{\override} command which must be used in a few special
+circumstances. Again, we shall not discuss or use it here.
+You may find the details in
+@ruser{Objects connected to the input}.
+@c Maybe explain in a later iteration -td
+
+@node The Internals Reference manual
+@section The Internals Reference manual
+
+@cindex Internals Reference
+
+@menu
+* Properties of layout objects::
+* Properties found in interfaces::
+* Types of properties::
+@end menu
+
+@node Properties of layout objects
+@subsection Properties of layout objects
+
+@cindex properties of layout objects
+@cindex properties of grobs
+@cindex grobs, properties of
+@cindex layout objects, properties of
+
+Suppose you have a slur in a score which, to your mind,
+appears too thin and you'd like to draw it a little heavier.
+How do you go about doing this? You know from the statements
+earlier about the flexibility of LilyPond that such a thing
+should be possible, and you would probably guess that an
+@code{\override} command would be needed. But is there a
+heaviness property for a slur, and if there is, how might it
+be modified? This is where the Internals Reference manual
+comes in. It contains all the information you might need to
+construct this and all other @code{\override} commands.
+
+Before we look at the Internals Reference a word of warning.
+This is a @strong{reference} document, which means there is
+little or no explanation contained within it: its purpose is
+to present information precisely and concisely. This
+means it might look daunting at first sight. Don't worry!
+The guidance and explanation presented here will enable you
+to extract the information from the Internals Reference for
+yourself with just a little practice.
+
+@cindex override example
+@cindex Internals Reference, example of using
+
+Let's use a concrete example with a simple fragment of real
+music:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+{
+ \time 6/8
+ {
+ r4 b8 b[( g]) g |
+ g[( e]) e d[( f]) a |
+ a g
+ }
+ \addlyrics {
+ The man who feels love's sweet e -- mo -- tion
+ }
+}
+@end lilypond
+
+Suppose now that we decide we would like the slurs to be a
+little heavier. Is this possible? The slur is certainly a
+layout object, so the question is, @q{Is there a property
+belonging to a slur which controls the heaviness?} To answer
+this we must look in the Internals Reference, or IR for short.
+
+The IR for the version of LilyPond you are using may be found
+on the LilyPond website at @uref{http://lilypond.org}. Go to the
+documentation page and click on the Internals Reference link.
+For learning purposes you should use the standard html version,
+not the @q{one big page} or the PDF. For the next few
+paragraphs to make sense you will need to actually do this
+as you read.
+
+Under the heading @strong{Top} you will see five links. Select
+the link to the @emph{Backend}, which is where information about
+layout objects is to be found. There, under the heading
+@strong{Backend}, select the link to @emph{All layout objects}.
+The page that appears lists all the layout objects used in your
+version of LilyPond, in alphabetic order. Select the link to
+Slur, and the properties of Slurs are listed.
+
+(An alternative way of finding this page is from the Notation
+Reference. On one of the pages that deals with slurs you may
+find a link to the Internals Reference. This link will
+take you directly to this page, but often it is easier to go
+straight to the IR and search there.)
+
+This Slur page in the IR tells us first that Slur objects are
+created by the
+Slur_engraver. Then it lists the standard settings. Note
+these are @strong{not} in alphabetic order. Browse down
+them looking for a property that might control the heaviness
+of slurs, and you should find
+
+@example
+@code{thickness} (number)
+ @code{1.2}
+ Line thickness, generally measured in @code{line-thickness}
+@end example
+
+This looks a good bet to change the heaviness. It tells us that
+the value of @code{thickness} is a simple @emph{number},
+that the default value is 1.2, and that the units are
+in another property called @code{line-thickness}.
+
+As we said earlier, there are few to no explanations in the IR,
+but we already have enough information to try changing the
+slur thickness. We see that the name of the layout object
+is @code{Slur}, that the name of the property to change is
+@code{thickness} and that the new value should be a number
+somewhat larger than 1.2 if we are to make slurs thicker.
+
+We can now construct the @code{\override} command by simply
+substituting the values we have found for the names, omitting
+the context. Let's use a very large value for the thickness
+at first, so we can be sure the command is working. We get:
+
+@example
+ \override Slur #'thickness = #5.0
+@end example
+
+Don't forget the @code{#'} preceding the
+property name and and @code{#} preceding the new value!
+
+The final question is, @q{Where should this command be
+placed?} While you are unsure and learning, the best
+answer is, @q{Within the music, before the first slur and
+close to it.} Let's do that:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+{
+ \time 6/8
+ {
+ % Increase thickness of all following slurs from 1.2 to 5.0
+ \override Slur #'thickness = #5.0
+ r4 b8 b[( g]) g |
+ g[( e]) e d[( f]) a |
+ a g
+ }
+ \addlyrics {
+ The man who feels love's sweet e -- mo -- tion
+ }
+}
+@end lilypond
+
+@noindent
+and we see that the slur is indeed heavier.
+
+So this is the basic way of constructing @code{\override}
+commands. There are a few more complications that we
+shall meet in later sections, but you now know all the
+essentials required to make up your own -- but you will
+still need some practice. This is provided in the examples
+which follow.
+
+@subheading Finding the context
+@cindex context, finding
+
+But first, what if we had needed to specify the Context?
+What should it be? We could guess that slurs are in
+the Voice context, as they are clearly closely associated
+with individual lines of music, but can we be sure? To
+find out, go back to the top of the IR page describing the
+Slur, where it says @q{Slur objects are created by: Slur
+engraver}. So slurs will be created in whichever context
+the @code{Slur_engraver} is in. Follow the link to the
+@code{Slur_engraver} page. At the very bottom it tells
+us that @code{Slur_engraver} is part of five Voice contexts,
+including the standard voice context, @code{Voice}, so our
+guess was correct. And because @code{Voice} is one of the
+lowest level contexts which is implied unambiguously by
+the fact that we are entering notes, we can omit it in this
+location.
+
+@subheading Overriding once only
+
+@cindex overriding once only
+@cindex once override
+@funindex \once
+
+As you can see, @emph{all} the slurs are thicker in the
+final example above. But what if we
+wanted just the first slur to be thicker? This is achieved
+with the @code{\once} command. Placed immediately before
+the @code{\override} command it causes it to change only the
+slur which begins on the @strong{immediately following} note.
+If the
+immediately following note does not begin a slur the command
+has no effect at all -- it is not remembered until a slur
+is encountered, it is simply discarded. So the command with
+@code{\once} must be
+repositioned as follows:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+{
+ \time 6/8
+ {
+ r4 b8
+ % Increase thickness of immediately following slur only
+ \once \override Slur #'thickness = #5.0
+ b[( g]) g |
+ g[( e]) e d[( f]) a |
+ a g
+ }
+ \addlyrics {
+ The man who feels love's sweet e -- mo -- tion
+ }
+}
+@end lilypond
+
+@noindent
+Now only the first slur is made heavier.