+The property can also be set locally, for example in a @code{\notes}
+block:
+
+@quotation
+\notes @{
+ \property Staff.Custos \override #'style = #'vaticana
+ c'1 d' e' d' \break c' d' e' d'
+@}
+@end quotation
+
+@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.
+
+Here we discuss how you can do that.
+
+Notational output is specified in so called grobs (graphic
+objects). Each grob carries with it a set of properties (grob
+properties) specific to that grob. For example, a stem grob has grob
+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
+specifically select a set of grobs at one point, and set properties as
+you wish, or secondly, you can (temporarily) modify the definition of a
+grob, thereby affecting an entire group of grobs.
+
+@menu
+* Tuning groups of grobs ::
+* Tuning per grob ::
+* What to tune?::
+* Text markup::
+@end menu
+
+@node Tuning groups of grobs
+@subsection Tuning groups of grobs
+
+@cindex grob description
+
+A grob definition is an 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 = #'((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 in the
+@code{autoBeamSettings} property.
+
+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 following shorthand:
+@code{\set} 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.
+
+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 functoin taking a grob a argument
+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-elt-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. Refer to the automatically generated
+documentation of the internals (available from the website).
+
+You need 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 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]
+\score { \notes \relative c' {
+ b-#"text"
+ c-#'(bold "text")
+ d-#'(lines "one" (bold "text"))
+ e-#'(music (named "noteheads-2" "flags-u3"))
+}
+\paper { linewidth = 10.\cm; } }
+@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 | @var{fontstyle}
+property: (@var{key} . @var{value})
+abbrev: @code{rows lines roman music bold italic named super sub text}
+@end example
+
+The markup is broken down and converted into a list of grob properties,
+which are prepended to the grop's 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
+@end table
+
+@var{fontstyle} may be any of @code{finger volta timesig mmrest mark
+script large Large dynamic}
projects / lilypond.git / commitdiff