+@node Fine tuning a piece
+@section Fine tuning a piece
+
+In this section, we show some ways to fine tune the final output of a
+piece. We do so using a single measure of a moderately complex piano
+piece: a Brahms intermezzo (opus 119, no. 1).
+@cindex Brahms, Johannes
+
+The code for the untuned example shows us some new things.
+
+@lilypondfile[verbatim]{brahms-original.ly}
+
+
+@cindex dynamics
+@cindex loudness
+@cindex forte
+@cindex crescendo
+@cindex @code{\<}
+@cindex @code{\!}
+
+The crescendo is ended at the half note by the escaped exclamation
+mark @code{\!}.
+
+Hairpin dynamics can be indicated using @code{\>} to start a
+decrescendo, and @code{\!} to end one. The crescendo is started using
+@code{\<} and also ended using @code{\!}. Absolute dynamics can be
+entered using @code{\p}, @code{\mf}, etc. All these commands apply to
+the complete chord where they are entered, but for syntactical
+reasons, they must be attached to one of the notes of the chord.
+
+@cindex fingering instructions
+
+Fingering indications are entered simply using @code{-@var{N}}, where
+@var{N} is a digit.
+
+Now that we have the basic piece of music entered, we want to fine
+tune it, so we get something that resembles the original printed
+edition by Schott/Universal Edition:
+
+@lilypondfile{brahms-tweaked.ly}
+
+@cindex tuning grob behavior
+
+The basic process that we follow is that we override defaults in the
+printing system. We do this by setting variables in so-called grobs.
+Printed symbols are internally represented by Graphical Objects
+(Grobs). Each grob is described by a bunch of settings. These setting
+determine the fonts, offsets, sub-routines to be called on the grob,
+etc. The initial values of these settings are set in the Scheme file
+@file{scm/grob-description.scm}.
+
+@cindex slur attachments
+
+We start with the slur: the slur in the upper part, running from the F
+sharp to the A, runs from stem to stem in the printed edition, while
+ours starts from the note head at the left. The following property
+setting forces all slurs to run from stem to stem (and not from or to
+note head)
+
+@example
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+@end example
+
+More precisely, this command extends the definition of the @code{Slur}
+object in the current @code{Voice}. The variable @code{attachment} is
+set to the pair of symbols @code{'(stem . stem)}.
+
+Although this is useful information, it is not very helpful: the
+lilypond backend supports approximately 240 variables like
+@code{attachment}, each with their own meaning and own type
+(eg. number, symbol, list, etc). Besides slur, LilyPond has 80
+different types of Grobs, that may be created in 14 different context
+types besides Voice.
+
+@cindex internal documentation
+@cindex finding grobs
+@cindex grob descriptiosn
+
+The interesting information is how you can figure out which properties
+to tune for your own scores. To discover this, you must have a copy of
+the internals document. This is a set of HTML pages, which should be
+included if you run a binary distribution@footnote{You can also
+compile them by executing @code{make -C Documentation/user/
+out/lilypond-internals.html} in the source package.}. This document is
+also available on the web: go to the lilypond website, click
+``Documentation: other'' on the side bar, click
+``lilypond-internals'', under information for users.
+
+You might want to bookmark either the HTML files on disk, or the one
+on the web. One word of caution is in place here: the internals
+documentation is generated from the definitions that lily uses. For
+that reason, it is strongly tied to the version of LilyPond that you
+use. Before you proceed, please make sure that you are using the
+documentation that corresponds to the LilyPond version that you use.
+
+Suppose that you wanted to tune the behavior of the slur. The first
+step is to get some general info on slurs in lilypond. Turn to the
+index, and look up slur. The section on slurs says
+@quotation
+The grob for this object is @internalsref{Slur}, generally in
+@internalsref{Voice} context.
+@end quotation
+
+So the grob for this object is called @code{Slur}, and slurs are
+created in the @code{Voice} context. If you are reading this tutorial
+in the HTML version, then you can simply click Slur, otherwise, you
+must look it up the internal documentation: click ``grob overview'' ,
+and select ``slur'' (the list is alphabetical.)
+
+Now you get a list of all the properties that the slur object
+supports, along with their default values. Among the properties we
+find the @code{attachment} property, leading to
+@example
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+@end example
+
+If you ran the previous example, you have unknowingly already used
+this kind of command. The @file{ly/property-init.ly} contains the
+definition of @code{\stemUp}
+@example
+ stemUp = \property Voice.Stem \set #'direction = #1
+@end example
+
+
+We also want to move around the fingering `3'. In the printed edition
+it is not above the stem, but a little lower, slightly left of the
+stem. From the user manual, we find that the associated grob is called
+@code{Fingering}, but how do we know if we should use @code{Voice} or
+@code{Staff}. In many cases, @code{Voice} is a safe bet, but you can
+also deduce this information from the internals documentation: if you
+visit the documentation of @code{Fingering}, you will notice
+@example
+Fingering grobs are created by: Fingering_engraver
+@end example
+
+
+
+Clicking @code{Fingering_engraver} will show you the documentation of
+the module responsible for interpreting the fingering instructions and
+translating them to a @code{Fingering} grob. Such a module is called
+an @emph{engraver}. The documentation of the @code{Fingering_engraver}
+says,
+@example
+Fingering_engraver is part of contexts: Voice and TabVoice
+@end example
+so tuning the settings for Fingering should be done using either
+@example
+ \property Voice.Fingering \set @dots{}
+@end example
+or
+@example
+ \property TabVoice.Fingering \set @dots{}
+@end example
+
+Since the @code{TabVoice} is only used for tab notation, we see that
+the first guess @code{Voice} was indeed correct.
+
+@cindex setting grob properties
+@cindex @code{extra-offset}
+
+For shifting the fingering, we use the grob property
+@code{extra-offset}. The following command manually adds an offset to
+the object. We move it a little to the left, and 1.8 staff space
+downwards.
+@example
+ \property Voice.Fingering \set #'extra-offset = #'(-0.3 . -1.8)
+@end example
+The @code{extra-offset} is a low-level feature: it moves around
+objects in the printout; the formatting engine is completely oblivious
+to these offsets.
+
+@cindex reverting grob properties
+@cindex undoing grob properties
+
+We only want to offset a single grob, so after the F-sharp, we must
+undo the setting. The technical term is to revert the grob property.
+@example
+ \property Voice.Fingering \revert #'extra-offset
+@end example
+
+@cindex property types
+@cindex translator properties
+@cindex grob properties
+@cindex music properties
+
+
+There is three different types of variables in LilyPond, something
+which is confusing at first (and for some, it stays like that).
+Variables such as @code{extra-offset} and @code{attachment} are called
+grob properties. They are something different from the translator
+properties, like @code{autoBeaming} and
+@code{automaticMelismata}. Finally, music expressions are internally
+also stored using properties, so-called music properties. You will
+encounter the latter type if you run Scheme functions on music using
+@code{\apply}.
+
+The second fingering instruction should be moved up a little, to avoid
+a collision with the slur. This could be achieved with
+@code{extra-offset}, but in this case, a simpler mechanism also
+works. We insert an empty text between the 5 and the note. The empty
+text pushes the fingering instruction away:
+@example
+ a^" "^#'(finger "5")
+@end example
+
+Lilypond tries to put fingering instructions closer to the notes as
+text instructions. To insert an empty text (@code{^" "}) between the
+finger and the note, we have disguised the fingering instruction as a
+text: @code{(finger "5")}.
+
+Normally, one would specify dynamics in a single voice, and start and
+end dynamics (such as @b{f} and @b{p}) will be aligned with
+hairpins. In this case, we want the decrescendo to be in a different
+place from the piano sign. We achieve this by putting the dynamic
+markings in different voices. The crescendo should be above the upper
+staff. This can be forced by the precooked command
+@example
+ \dynamicsUp
+@end example
+
+However, if you do that, the decrescendo will be too close to the
+upper voice, and collide with the stems. Looking at the manual for
+dynamics, we notice that ``Vertical positioning of these symbols is
+handled by the @internalsref{DynamicLineSpanner} grob.''. If we turn
+to the documentation of @code{DynamicLineSpanner}, we find that the
+@code{DynamicLineSpanner} supports several so-called
+`interfaces'. This grob not only puts dynamic objects next to the
+staff (@code{side-position-interface}), but it also groups dynamic
+objects (@code{axis-group-interface}), is considered a dynamic sign
+itself (@code{dynamic-interface}) and is a grob: it has the
+@code{grob-interface}, with all the variables that come with it.
+
+For the moment, we are interested in the side positioning:
+@quotation
+ side-position-interface
+
+ Position a victim object (this one) next to other objects (the
+ support). In this case, the direction signifies where to put the
+ victim object relative to the support (left or right, up or down?)
+@end quotation
+Between the grob and its support (in this case: the notes in the voice
+going down), there should be more space. This space is controlled by
+@code{padding}, so we increase it.
+@example
+ \property Voice.DynamicLineSpanner \override #'padding = #5.0
+@end example
+
+This command is almost like the command for setting slur attachments,
+but subtly different in its details. Grob properties can be
+manipulated with two commands: @code{\override} extends the grob
+variables with a setting, and @code{\revert} releases this
+setting. This has a certain theoretical appeal: the operations are
+simple and symmetric. For practical use, it can be cumbersome. Both
+commands act like parentheses: you should carefully balance the use of
+@code{\override} and @code{\revert}. The @code{\set} command is more
+friendly: it first does a @code{\revert} followed by @code{\override}.
+
+Finally, Brahms uses music notation is a slightly unorthodox way. Ties
+usually happen only within one voice. In this piece, the composer
+gladly produces ties that jump voices. We deal with this by faking
+these ties: whenever we need such a tie, we insert a notehead in a
+different voice, and blank the stem. This is done in the following
+snippet of code.
+
+@example
+ \property Voice.Stem \set #'transparent = ##t
+ d'
+ \property Voice.Stem \revert #'transparent
+@end example
+
+Finally, the last tie is forced up using @code{\tieUp}.
+
+