@node Tweaking output
@chapter Tweaking output
-This chapter discusses how modify output. LilyPond is extremely
+This chapter discusses how to modify output. LilyPond is extremely
configurable; virtually every fragment of output may be changed.
@menu
+* Moving objects::
* Fixing overlapping notation::
* Common tweaks::
* Default files::
-* Advanced tweaks with scheme::
+* Advanced tweaks with Scheme::
@end menu
-@node Fixing overlapping notation
-@section Fixing overlapping notation
+@node Moving objects
+@section Moving objects
-This may come as a surprise, but LilyPond isn't perfect. Some notation
+This may come as a surprise, but LilyPond is not perfect. Some notation
elements can overlap. This is unfortunate, but (in most cases) is easily
solved.
can move it horizontally or vertically. This is done with the
@code{extra-offset} property. It is slightly more complicated and can
cause other problems. When we move objects with @code{extra-offset},
-the movement is done after LilyPond has placed all other objects. This means
+the movement is done after LilyPond has placed all other objects. This
+means
that the result can overlap with other objects.
@lilypond[quote,fragment,ragged-right,verbatim,relative=2]
c4^"piu mosso" d e f
@end lilypond
-
@seealso
This manual: @ref{The \override command}, @ref{Common tweaks}.
+@node Fixing overlapping notation
+@section Fixing overlapping notation
+
+In @ref{Moving objects}, we saw how to move a @code{TextScript}
+object. The same mechanism can be used to move other types of
+objects; simply replace @code{TextScript} with the name of
+another object.
+
+To find the object name, look at the ``@strong{see also}'' at
+bottom of the relevant documentation page. For example, at
+the bottom of @ref{Dynamics}, we see
+
+@quotation
+@seealso
+
+Program reference: @internalsref{DynamicText}, @internalsref{Hairpin}.
+Vertical positioning of these symbols is handled by
+@internalsref{DynamicLineSpanner}.
+@end quotation
+
+@noindent
+So to move dynamics around, we use
+
+@example
+\override DynamicLineSpanner #'padding = #2.0
+@end example
+
+We cannot list every object, but here is a list of the most
+common objects.
+
+@multitable @columnfractions .33 .66
+@headitem Object type @tab Object name
+@item Dynamics @tab @code{DynamicLineSpanner}
+@item Ties @tab @code{Tie}
+@item Slurs @tab @code{Slur}
+@item Articulations @tab @code{Script}
+@item Fingerings @tab @code{Fingering}
+@item Text e.g. @code{^"text"} @tab @code{TextScript}
+@item Rehearsal / Text marks @tab @code{RehearsalMark}
+@end multitable
+
+
@node Common tweaks
@section Common tweaks
The complete list of modifications available for each type of
object (like slurs or beams) are documented in the Program
-Reference. However, many layout objects share properties, which can be
+Reference. However, many layout objects share properties which can be
used to apply generic tweaks.
@itemize @bullet
-@cindex @code{padding}
-@item The @code{padding} property can be set to increase
+@cindex padding
+
+@item
+The @code{padding} property can be set to increase
(or decrease) the distance between symbols that are printed
above or below notes. This applies to all objects with
@code{side-position-interface}.
Note in the second example how important it is to figure out what
context handles a certain object. Since the @code{MetronomeMark} object
-is handled in the Score context, property changes in the @code{Voice}
-context will not be noticed. For more details, see
+is handled in the @code{Score} context, property changes in the
+@code{Voice} context will not be noticed. For more details, see
@ref{Constructing a tweak}.
-@cindex @code{extra-offset}
-@item The @code{extra-offset} property moves objects around
+@cindex extra-offset
+
+@item
+The @code{extra-offset} property moves objects around
in the output; it requires a pair of numbers. The first number
controls horizontal movement; a positive number will
-move the object to the right. The second number controls vertical
+move the object to the right. The second number controls vertical
movement; a positive number will move it higher. The
@code{extra-offset} property is a low-level feature: the
formatting engine is completely oblivious to these offsets.
\stemUp
f-5
\once \override Fingering
- #'extra-offset = #'(-0.3 . -1.8)
+ #'extra-offset = #'(-0.3 . -1.8)
f-5
@end lilypond
-@item
+ @item
Setting the @code{transparent} property will cause an object to be printed
in `invisible ink': the object is not printed, but all its other
behavior is retained. The object still takes up space, it takes part in
Distances in LilyPond are measured in staff-spaces, while most
thickness properties are measured in line-thickness. Some
properties are different; for example, the thickness of beams
-is measured in staff-spaces. For more information, see the
+are measured in staff-spaces. For more information, see the
relevant portion of the program reference.
@file{ly/declarations-init.ly} define all the common tweaks.
-@node Advanced tweaks with scheme
-@section Advanced tweaks with scheme
+@node Advanced tweaks with Scheme
+@section Advanced tweaks with Scheme
We have seen how LilyPond output can be heavily modified using
commands like
@code{\override TextScript #'extra-offset = ( 1 . -1)}. But
-we have even more power if we use scheme. For a full explantion
-of this, see @ref{Interfaces for programmers}.
+we have even more power if we use Scheme. For a full explantion
+of this, see the @ref{Scheme tutorial} and
+@ref{Interfaces for programmers}.
-We can use scheme to simply @code{\override} commands,
+We can use Scheme to simply @code{\override} commands,
@lilypond[quote,verbatim,ragged-right]
padText = #(define-music-function (parser location padding) (number?)
We can use it to create new commands,
@lilypond[quote,verbatim,ragged-right]
-tempoMark = #(define-music-function (parser location marktext padding) (string? number?)
+tempoMark = #(define-music-function (parser location padding marktext)
+ (number? string?)
#{
\once \override Score . RehearsalMark #'padding = $padding
\once \override Score . RehearsalMark #'no-spacing-rods = ##t
\relative c'' {
c2 e
-\tempoMark #"Allegro" #3.0
+\tempoMark #3.0 #"Allegro"
g c
}
@end lilypond
-Even music expressions can be passed in. Note that since we
-want an articulation attached to the second variable, we
-must #####.
+Even music expressions can be passed in.
@lilypond[quote,verbatim,ragged-right]
pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)