+@end example
+
+@c . {Tuning output}
+@node Tuning output
+@section Tuning output
+
+LilyPond tries to take as much formatting as possible out of your
+hands. Nevertheless, there are situations where it needs some help, or
+where you want to override its decisions. In this section we discuss
+ways to do just that.
+
+Notation output is specified in so called grobs (graphic objects). Each
+grob carries with it a set of properties (grob properties) specific to
+that object. For example, a stem grob has properties that specify its
+direction, length and thickness.
+
+
+The most common way of tuning the output is to alter the values of these
+properties. There are two ways of doing that: first, you can temporarily
+change the definition of a certain type of grob, thus affecting a whole
+set of objects. Second, you can select one specific object, and set a
+grob property.
+
+@menu
+* Tuning groups of grobs ::
+* Tuning per grob ::
+* What to tune?::
+* Font selection::
+* Text markup::
+@end menu
+
+@node Tuning groups of grobs
+@subsection Tuning groups of grobs
+
+@cindex grob description
+
+A grob definition is a Scheme association list, that is stored in a context
+property. By assigning to that property (using plain @code{\property}),
+you can change the resulting grobs.
+
+@lilypond[verbatim, fragment]
+c'4 \property Voice.Stem \override #'meta = #'((interfaces . ())) c'4
+@end lilypond
+
+The @code{\property} statement effectively empties the definition of the
+Stem object. One of the effects is that property specifying how it
+should be printed is erased, with the effect of rendering it invisible.
+
+@cindex \override
+@cindex \revert
+@cindex \set
+
+This mechanism is fairly crude, since you can only set, but not modify,
+the definition of a grob. For this reason, there is a more advanced
+mechanism: you can add a property on top of an existing definition, or
+remove a property: @code{\override} adds a settings, @code{\revert}
+removes that setting.
+
+@lilypond[verbatim]
+c'4 \property Voice.Stem \override #'thickness = #4.0
+c'4 \property Voice.Stem \revert #'thickness
+c'4
+@end lilypond
+
+For the digirati, the grob description is an Scheme association
+list. Since it is singly linked, we can treat it as a stack, and
+@code{\override} and @code{\revert} are just push and pop
+operations. This pushing and popping is also used for overriding automatic
+beaming settings.
+
+If you revert a setting which was not set in the first place, then it
+has no effect. However, if the setting was set as a system default, it
+may remove the default value, and this may give surprising results,
+including crashes. In other words, if you use @code{\override} and
+@code{\revert}, be sure to balance the overrides and reverts.
+
+If balancing them is too much work, use the @code{\set} shorthand. It
+performs a revert followed by an override:
+@example
+\property Voice.Stem \set #'thickness = #2.0
+@end example
+
+Formally the syntax for these constructions is
+@example
+\property @var{context}.@var{grobname} \override @var{symbol} = @var{value}
+\property @var{context}.@var{grobname} \set @var{symbol} = @var{value}
+\property @var{context}.@var{grobname} \revert @var{symbol}
+@end example
+Here @var{symbol} is a Scheme expression of symbol type, @var{context}
+and @var{grobname} are strings and @var{value} is a Scheme expression.
+
+@refbugs
+
+LilyPond will hang or crash if @var{value} contains cyclic references.
+
+
+
+@node Tuning per grob
+@subsection Tuning per grob
+
+@cindex \outputproperty
+
+A second way of tuning grobs is the more arcane @code{\outputproperty}
+feature.
+Syntax is as follows
+@example
+\outputproperty @var{predicate} @var{symbol} = @var{value}
+@end example
+Here @code{predicate} is a Scheme function taking a grob argument, and
+returning a boolean. This statement is processed by the
+@code{Output_property_engraver}. It instructs the engraver to feed all
+grobs that it sees to @var{predicate}. Whenever the predicate returns
+true, the grob property @var{symbol} will be set to @var{value}.
+
+You will need to combine this statement with @code{\context} to select
+the appropriate context to apply this to.
+
+If possible, avoid this feature: the semantics are not very clean, and
+the syntax and semantics are up for rewrite.
+
+Here are some random examples:
+
+@lilypond[fragment,verbatim,singleline]
+\relative c'' { c4
+ \context Staff \outputproperty
+ #(make-type-checker 'note-head-interface)
+ #'extra-offset = #'(0.5 . 0.75)
+ <c8 e g> }
+@end lilypond
+
+@cindex @code{extra-offset}
+
+This selects all note heads occurring at current staff level, and sets
+the @code{extra-offset} of those heads to @code{(0.5,0.75)}, shifting
+them up and right.
+
+Move the text "m.d.", but not the fingering instruction "2".
+@lilypond[verbatim,singleline]
+#(define (make-text-checker text)
+ (lambda (grob) (equal? text (ly-get-grob-property grob 'text))))
+
+\score {
+ \notes\relative c''' {
+ \property Voice.Stem \set #'direction = #1
+ \outputproperty #(make-text-checker "m.d.")
+ #'extra-offset = #'(-3.5 . -4.5)
+ a^2^"m.d."
+ }
+}
+@end lilypond
+
+
+
+
+@node What to tune?
+@subsection What to tune?
+
+This all tells you how to tune grobs, but what variables are there? The
+question is not answered in this manual (although you may encounter
+some examples.).
+
+Grob properties are tied directly to the implementation of LilyPond, and
+they are thus a moving target. Documentation of such variables are part
+of the generated documentation: this documentation is generated from the
+sourcecode of lily for each version, so it is usually mch more up to
+date than this manual. It should be available from the same place where
+you got this manual.
+
+To decide how to tune a grob, you need to find the following information
+@itemize @bullet
+@item
+which grob to modify
+@item
+which property to modify
+@item
+which context the grob comes from.
+@end itemize
+
+Included with the automatically generated documentation is a master list
+of grobs. Each one can be clicked, taking you to a overview of the
+available properties.
+
+There is also a master list of contexts. Clicking each takes you to an
+overview of the context, listing which grob types are created there.
+
+
+@node Font selection
+@subsection Font selection
+
+Most graphics in LilyPond are composed of characters of fonts. You can
+alter the characteristics of the font by setting certain grob
+properties. The mechanism that is used for this resembles LaTeX's New
+Font Selection Scheme. Within this scheme, a font is entirely
+characterized by its font name.
+
+For each grob that uses fonts (in other words, each grob that supports
+@code{font-interface}) a font-name must be selected before it can be
+printed. The font name is selected by looking at a number of grob
+properties:
+
+@table @code
+@item font-family
+ The general class of the typeface. Supported are roman (Computer
+Modern), braces (for piano staff braces), music (the standard music
+font), dynamic (font for dynamic signs) and typewriter
+
+@item font-shape
+ A symbol indicating the shape of the font, a finer gradation than
+ font-family. Choices are italic and upright
+@item font-series
+ Symbol indicating the serie of the font. Series form a finer gradation
+ than font-shape. Choices are medium and bold.
+
+@item font-relative-size
+ A number indicating the size relative the standard size. For example,
+ with 20pt staff height, relative size -1 corresponds to 16pt staff
+ height, and relative size +1 corresponds to 23 pt staff height.
+
+@item font-design-size
+A number indicating the design size of the font.
+
+This is a feature of the Computer Modern Font: each point size has a
+slightly different design. Smaller design sizes are relatively wider,
+which enhances readability. Scalable type faces such TrueType and Adobe
+Type1 usually come as ``one design fits all sizes''.
+
+@item font-name
+ The name of the font, without the design size, eg. @code{cmr},
+@code{cmti}, etc. Setting this overrides font-family, font-shape and
+font-series.
+
+@end table
+
+The font is selected by taking the first font that satisfies all
+qualifiers specified. You can override any of these fields through
+@code{\override} and @code{\revert}. The special value @code{*} matches
+any value for that qualifier.
+
+@example
+ \property Lyrics.LyricText \override #'font-series = #'bold
+ \property Lyrics.LyricText \override #'font-shape = #'*
+@end example
+
+@cindex @code{font-style}
+
+There are also pre-cooked font selection qualifiers. These are selected
+through the grob property @code{font-style}. For example, the style
+@code{finger} selects family @code{number} and relative size @code{-3}.
+Styles available include: volta, finger, tuplet, timesig, mmrest,
+script, large, Large and dynamic.
+
+The style sheets and tables for selecting fonts are located in
+@file{scm/font.scm}. Refer to this file for more information.
+
+@refbugs
+
+Relative size is not linked to any real size. There is no mechanism to
+select magnifications of fonts, meaning that you can not scale fonts
+continuoussly. There is no style sheet provided for other fonts besides
+the @TeX{} family.
+
+@cindex font selection
+@cindex font magnification
+@cindex @code{font-interface}
+
+@refbugs
+
+
+@node Text markup
+@subsection Text markup
+@cindex text markup
+@cindex markup text
+
+LilyPond has an internal mechanism to typeset texts. You can
+form text markup expressions by composing scheme expressions
+in the following way.
+
+@lilypond[verbatim, singleline]
+ \relative c' {
+ \fatText
+ a^#"upright"
+ b_#'(bold "bold")
+ c^#'(italic "italic")
+ d_#'((bold italic) "ff")
+ e^#'(dynamic "ff")
+ f_#'(lines "one" (bold "two"))
+ g^#'(music "noteheads-2" "flags-u3")
+ }
+@end lilypond
+
+Normally, the Scheme markup text is stored in the @code{text} property
+of a grob. Formally, it is defined as follows:
+
+@example
+text: string | (head? text+)
+head: markup | (markup+)
+markup-item: property | abbrev
+property: (@var{key} . @var{value})
+abbrev: @code{rows lines roman music bold italic named super sub text}
+ @code{finger volta timesig mmrest mark script large Large dynamic}
+@end example
+
+The markup is broken down and converted into a list of grob properties,
+which are prepended to the property list. The @var{key}-@var{value}
+pair is a grob property.
+
+The following abbreviations are currently defined:
+
+@table @code
+@item rows
+horizontal mode: set all text on one line (default)
+@item lines
+ vertical mode: set every text on new line
+@item roman
+ select roman font
+@item music
+ select feta font
+@item bold
+ select bold series
+@item italic
+ select italic shape
+@item named
+ lookup by character name
+@item text
+ plain text lookup (by character value)
+@item super
+ superscript
+@item sub
+ subscript
+@item finger
+ select fingering number fontstyle
+@item volta
+ select volta number fontstyle
+@item timesig
+ select time signature number fontstyle
+@item mmrest
+ select multi measure rest number fontstyle
+@item mark
+ select mark number fontstyle
+@item script
+ select scriptsize roman fontstyle
+@item large
+ select large roman fontstyle
+@item Large
+ select Large roman fontstyle
+@item dynamic
+ select dynamics fontstyle
+@end table
+
+It is possible to use @TeX{} commands in the strings, but this should be
+avoided because this makes it impossible for LilyPond to compute the
+exact length of the string, which may lead to collisions. Also, @TeX{}
+commands won't work with direct postscript output.