+@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 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 tells us first that there @emph{is} a property that
+controls thickness, that its value is a simple @emph{number},
+that the default value is 1.2, and that the units are
+in another property called @code{line-thickness}. This looks
+a good bet to change the heaviness.
+
+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.
+
+But what is the Context? 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.
+
+We can now construct the @code{\override} command by simply
+substituting the values we have found for the names. 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 Voice.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 Voice.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
+
+@cindex overriding once only
+@cindex once override
+@funindex \once
+
+As you can see, all the slurs are thicker. 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 affect only the
+slur on the @strong{immediately following} note. If the
+immediately following note does not have a slur the command
+has no effect. So the command 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 Voice.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
+
+Finally, what if we wanted just the first two slurs to be
+heavier? Well, we could use two commands, each preceded by
+@code{\once} placed immediately before each of the notes where
+the slurs begin:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+{
+ \time 6/8
+ {
+ r4 b8
+ % Increase thickness of immediately following slur only
+ \once \override Voice.Slur #'thickness = #5.0
+ b[( g]) g |
+ % Increase thickness of immediately following slur only
+ \once \override Voice.Slur #'thickness = #5.0
+ g[( e]) e d[( f]) a | a g
+ }
+ \addlyrics { The man who feels love's sweet e -- mo -- tion }
+}
+@end lilypond
+
+@cindex revert
+@funindex \revert
+
+@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:
+
+@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
+{
+ \time 6/8
+ {
+ r4 b8
+ % Increase thickness of all following slurs from 1.2 to 5.0
+ \override Voice.Slur #'thickness = #5.0
+ b[( g]) g |
+ g[( e])
+ % Revert thickness of all following slurs to default of 1.2
+ \revert Voice.Slur #'thickness
+ e d[( f]) a | a 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, but with progressively fewer words
+of guidance and explanation.
+
+@node Properties found in interfaces
+@subsection Properties found in interfaces
+
+@cindex interface properties
+@cindex properties in interfaces
+
+Suppose now that we wish to color a slur red. We would go
+to the properties on Slurs in the IR as described in the
+previous section, and look in vain, because there is nothing
+there that looks like it might change the color. This is
+because the color property is one that is common to all
+layout 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{grob-interface}. (Remember, grob is short for
+@q{graphical object}, itself another name for a layout object.)
+
+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 the Slur. At the
+bottom of the page is a list of clickable (in the html versions
+of the IT) interfaces which the Slur supports. The list has
+three items: @code{spanner-interface}, @code{slur-interface}
+and @code{grob-interface}.
+
+The @code{spanner-interface} holds properties common to
+spanners -- objects which extend over several notes --
+as do Slurs.
+
+The @code{slur-interface} holds properties common to ordinary
+slurs and phrasing slurs.
+
+The @code{grob-interface} holds properties common to all
+layout objects, and it is here that you will find the
+@code{color} property, which appears as
+
+@example
+color(list)
+ The color of this grob
+@end example
projects / lilypond.git / commitdiff