+@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). Both fragments (the
+tuned and the untuned versions) are in @file{input/tutorial/}.
+
+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{\!}
+
+Hairpin dynamics can be easily added to Lilypond scores. Beginning a
+crescendo is indicated with @code{\<} and ending a crescendo is indicated
+with @code{\!}. A decrescendo can be indicated with @code{\>} and
+@code{\!}. Absolute dynamics (sometimes called ``Letter dynamics'') can
+be entered using @code{\p}, @code{\mf}, etc. All these dynamics will
+apply to the whole 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 with @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 that we get something that resembles the original printed
+edition by Schott/Universal Edition:
+
+@lilypondfile{brahms-tweaked.ly}
+
+@cindex tuning graphical objects
+
+Fine tuning involves overriding the defaults of the printing system.
+We do this by setting variables which control how Lilypond prints
+symbols. Printed symbols are called graphical objects (often
+abbreviated to @emph{grob}). Each object is described by a bunch of
+settings. Every setting is a variable: it has a name and a value
+which you can change. These values determine the fonts, offsets,
+sub-routines to be called on the object, 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 in the upper part, running from F sharp to A. In
+the printed edition, this slur runs from stem to stem; in our version,
+the slur begins at the note head of the F sharp. The following property
+setting forces all slurs to run from stem to stem (not from or to note
+heads!).
+
+@example
+ \property Voice.Slur \set #'attachment = #'(stem . stem)
+@end example
+
+More precisely, this command modifies 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 fixes the slur, it isn't very helpful for fine tuning in
+general: the lilypond back-end 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 graphical objects, that may be created in 14
+different context types besides Voice.
+
+@cindex internal documentation
+@cindex finding graphical objects
+@cindex graphical object descriptions
+
+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 installed a binary distribution@footnote{You can also
+compile them by executing @code{make -C Documentation/user/
+out/lilypond-internals.html} in the source package.}. These HTML pages
+are also available on the web: go to the lilypond website, click
+``Documentation: Index'' on the side bar, look in the ``Information for
+uses'' section, and click on ``Documentation of internals''.
+
+You might want to bookmark either the HTML files on your disk, or the one
+on the web (the HTML on your hard drive will load much faster than the
+ones on the web!). One word of caution: 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 version of LilyPond that you are using.
+
+@c TODO: the quote is incorrect, although that shouldn't be a big
+@c problem for the reader.
+Suppose that you wanted to tune the behavior of the slur. The first
+step is to get some general information 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 graphical object 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 should 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 with its default setting.
+The property documentation explains that the following setting will
+produce the desired effect:
+@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
+
+@c this is a long section, and adding an extra space here helps to
+@c break it into smaller subsections and thus is easier to understand.
+@separate
+
+Next we want to move the fingering `3'. In the printed edition it is
+not above the stem, but a little lower and slightly left of the stem.
+From the user manual we find that the associated graphical object 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} object. 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 object properties
+@cindex @code{extra-offset}
+
+For shifting the fingering, we use the 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. The unit of these offsets are staff-spaces. The
+first number controls left-right movement; a positive number will move
+the object to the right. The second number controls up-down movement;
+a positive number will move it higher.
+
+@cindex reverting object properties
+@cindex undoing object properties
+
+We only want to offset a single object, so after the F-sharp we must
+undo the setting. The technical term is to revert the property.
+@example
+ \property Voice.Fingering \revert #'extra-offset
+@end example
+
+@cindex property types
+@cindex translator properties
+@cindex grob properties
+@cindex music properties
+@separate
+
+There are three different types of variables in LilyPond, something
+which can be confusing at first (and for some people it stays confusing
+:). Variables such as @code{extra-offset} and @code{attachment} are
+called grob properties. They are not the same as translator properties,
+like @code{autoBeaming}. Finally, music expressions are internally
+stored using properties (so-called music properties). You will encounter
+music properties 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 as close to the notes as
+possible. To make sure that Lilypond doesn't do that, we disguise the
+fingering as text: @code{(finger "5")}.
+
+@separate
+
+Normally one would specify all dynamics in the same voice, so that
+dynamics (such as @b{f} and @b{p}) will be aligned with hairpins. But
+in this case, we don't want the decrescendo to be aligned with 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 using 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
+@code{DynamicLineSpanner} supports several so-called `interfaces'. This
+object 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 an object. It has the standard
+@code{grob-interface} with all the variables that come with it.
+
+For the moment we are interested in 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 object 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
+variables with a setting, and @code{\revert} releases this
+setting. This has a certain theoretical appeal: the operations are
+simple and symmetric. But for practical use, it can be cumbersome. The
+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}.
+
+@separate
+
+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'
+@end example
+Blanking the stem should be done for only one object. One of the ways
+to achieve that, is by setting the property before a note. Reverting
+it afterwards is tedious, so for setting a property only once, we have
+the syntax @code{\once}: it reverts the property directly before
+proceeding to the next step in time.
+
+The @code{\once} keyword is added to @code{\property}.
+
+
+Finally, the last tie is forced up using @code{\tieUp}.
+
+@separate
+
+Here's the complete ``fine tuned'' version, which includes all the
+modifications we discussed in this section:
+
+@lilypondfile[verbatim]{brahms-tweaked.ly}
+
+