@node Tweaking output
@chapter Tweaking output
-Tweak explanation.
+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::
-* Advanced tweaks with scheme::
+* Default files::
+* Fitting music onto fewer pages::
+* Advanced tweaks with Scheme::
+* Avoiding tweaks with slower processing::
@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.
\once \override TextScript #'staff-padding = #2.6
c4^"piu mosso" fis a g
\break
-c,,4^"piu mosso" b a b
+c'4^"piu mosso" b a b
\once \override TextScript #'padding = #2.6
c4^"piu mosso" d e f
\once \override TextScript #'staff-padding = #2.6
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]
This tweaks the display of text for the next note. If the note has
no text, this tweak does nothing (and does @strong{not} wait until
-the next bit of text).
+the next bit of text). To change the behavior of everything after
+the command, omit the @code{\once}. To stop this tweak, use a
+@code{\revert}. This is explained in depth in
+@ref{The \override command}.
@lilypond[quote,fragment,ragged-right,verbatim,relative=3]
c4^"piu mosso" b
\override TextScript #'padding = #2.6
c4^"piu mosso" d e f
c4^"piu mosso" d e f
+\revert TextScript #'padding
+c4^"piu mosso" d e f
@end lilypond
-
@seealso
This manual: @ref{The \override command}, @ref{Common tweaks}.
-@menu
-* Common tweaks::
-@end menu
+@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 vertically, 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 (vertically) @tab @code{DynamicLineSpanner}
+@item Dynamics (horizontally) @tab @code{DynamicText}
+@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
-@c Should we point at ly/property-init.ly ? -gp
Some overrides are so common that predefined commands are provided as
-short-cuts, for example, @code{\slurUp} and @code{\stemDown}. These
-commands are described in
-@ifhtml
-the
-@end ifhtml
-@c @ref{Notation manual},
-Notation manual
-@c FIXME
-under the sections for slurs and stems
-respectively.
-
-The exact tuning possibilities for each type of layout object are
-documented in the program reference of the respective
-object. However, many layout objects share properties, which can be
-used to apply generic tweaks. We mention a few of these:
+short-cuts, such as @code{\slurUp} and @code{\stemDown}. These
+commands are described in the Notation Reference under the appropriate
+sections.
+
+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
+used to apply generic tweaks.
@itemize @bullet
-@item The @code{extra-offset} property, which
-@cindex @code{extra-offset}
-has a pair of numbers as value, moves objects around in the printout.
-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. The units of these
-offsets are staff-spaces. The @code{extra-offset} property is a
-low-level feature: the formatting engine is completely oblivious to
-these offsets.
+
+@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}.
+
+@lilypond[quote,fragment,relative=1,verbatim]
+c2\fermata
+\override Script #'padding = #3
+b2\fermata
+@end lilypond
+
+@lilypond[quote,fragment,relative=1,verbatim]
+% This will not work, see below:
+\override MetronomeMark #'padding = #3
+\tempo 4=120
+c1
+% This works:
+\override Score.MetronomeMark #'padding = #3
+\tempo 4=80
+d1
+@end lilypond
+
+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 @code{Score} context, property changes in the
+@code{Voice} context will not be noticed. For more details, see
+@ref{Constructing a tweak}.
+
+@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
+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.
In the following example, the second fingering is moved a little to
the left, and 1.8 staff space downwards:
-@cindex setting object properties
-
@lilypond[quote,fragment,relative=1,verbatim]
\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
and blanking the first up-stem in that voice, the tie appears to cross
voices:
+
@lilypond[quote,fragment,relative=2,verbatim]
<< {
\once \override Stem #'transparent = ##t
} >>
@end lilypond
-@item
-The @code{padding} property for objects with
-@cindex @code{padding}
-@code{side-position-interface} can be set to increase the distance between
-symbols that are printed above or below notes. We provide two
-examples; a more elaborate explanation is in @ref{Constructing a
-tweak}:
-
-@lilypond[quote,fragment,relative=1,verbatim]
-c2\fermata
-\override Script #'padding = #3
-b2\fermata
-@end lilypond
+To make sure that the just blanked stem doesn't sqeeuze the too much
+tie, we also lengthen the stem, by setting the @code{length} to
+@code{8},
-@lilypond[quote,fragment,relative=1,verbatim]
-% This will not work, see below:
-\override MetronomeMark #'padding = #3
-\tempo 4=120
-c1
-% This works:
-\override Score.MetronomeMark #'padding = #3
-\tempo 4=80
-d1
+@lilypond[quote,fragment,relative=2,verbatim]
+<< {
+ \once \override Stem #'transparent = ##t
+ \once \override Stem #'length = #8
+ b8~ b8\noBeam
+} \\ {
+ b[ g8]
+} >>
@end lilypond
-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.
-
@end itemize
-Some tweakable options are called ``subproperties'' and reside inside
-properties. To tweak those, use
-
-@example
-\override Stem #'details #'beamed-lengths = #'(4 4 3)
-@end example
-
@cindex Tweaks, distances
@cindex Distances
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.
-More specific overrides are also possible. The next section
-discusses in depth how to figure out these statements for yourself.
+@node Default files
+@section Default files
-@node Advanced tweaks with scheme
-@section Advanced tweaks with scheme
+The Program Reference documentation contains a lot of information
+about LilyPond, but even more information can be gathered from
+looking at the internal LilyPond files.
+
+Some default settings (such as the definitions for
+@code{\header@{@}}s) are stored as @code{.ly} files. Other
+settings (such as the definitions of markup commands) are
+stored as @code{.scm} (Scheme) files. Further explanation is
+outside the scope of this manual; users should be warned that
+a substantial amount of technical knowledge or time is required
+to understand these files.
+
+@itemize @bullet
+
+@item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
+
+@item OSX:
+@file{@var{installdir}/LilyPond.app/Contents/Resources/share/lilypond/current/}.
+To access this, either @code{cd} into this directory from the
+Terminal, or control-click on the LilyPond application and select
+"Show Package Contents".
+
+@item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
+
+@end itemize
+
+The @file{ly/} and @file{scm/} directories will be of
+particular interest. Files such as @file{ly/property-init.ly} and
+@file{ly/declarations-init.ly} define all the common tweaks.
+
+
+@node Fitting music onto fewer pages
+@section Fitting music onto fewer pages
+
+Sometimes you can end up with one or two staves on a second
+(or third, or fourth...) page. This is annoying, especially
+if you look at previous pages and it looks like there is plenty
+of room left on those.
+
+When investigating layout issues, @code{annotate-spacing} is
+an invaluable tool. This command prints the values of various
+layout spacing commands; see @ref{Displaying spacing} for more
+details. From the output of @code{annotate-spacing}, we can
+see which margins we may wish to alter.
+
+Other than margins, there are a few other options to save space:
+
+@itemize
+@item
+You may tell LilyPond to place systems as close together as
+possible (to fit as many systems as possible onto a page), but
+then to space those systems out so that there is no blank
+space at the bottom of the page.
+
+@example
+\paper @{
+between-system-padding = #0.1
+between-system-space = #0.1
+ragged-last-bottom = ##f
+ragged-bottom = ##f
+@}
+@end example
+
+@item
+You may force the number of systems (i.e., if LilyPond wants
+to typeset some music with 11 systems, you could force it to
+use 10).
+
+@example
+\paper @{
+system-count = #10
+@}
+@end example
+
+@item
+Avoid (or reduce) objects which increase the vertical size of
+a system. For example, volta repeats (or alternate repeats)
+require extra space. If these repeats are spread over two
+systems, they will take up more space than one system with
+the volta repeats and another system without.
+
+Another example is moving dynamics which ``stick out'' of
+a system.
+
+@lilypond[verbatim,quote,fragment]
+\relative c' {
+ e4 c g\f c
+ \override DynamicLineSpanner #'padding = #-1.8
+ \override DynamicText #'extra-offset = #'( -2.1 . 0)
+ e4 c g\f c
+}
+@end lilypond
+
+@item
+Alter the horizontal spacing via @code{SpacingSpanner}. See
+@ref{Changing horizontal spacing} for more details.
+
+@lilypond[verbatim,quote]
+\score {
+ \relative c'' {
+ g4 e e2 | f4 d d2 | c4 d e f | g4 g g2 |
+ g4 e e2 | f4 d d2 | c4 e g g | c,1 |
+ d4 d d d | d4 e f2 | e4 e e e | e4 f g2 |
+ g4 e e2 | f4 d d2 | c4 e g g | c,1 |
+ }
+ \layout {
+ \context {
+ \Score
+ \override SpacingSpanner
+ #'base-shortest-duration = #(ly:make-moment 1 4)
+ }
+ }
+}
+@end lilypond
+
+@end itemize
+
+
+@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.
+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,
+
+@lilypond[quote,verbatim,ragged-right]
+padText = #(define-music-function (parser location padding) (number?)
+#{
+ \once \override TextScript #'padding = #$padding
+#})
+
+\relative c''' {
+ c4^"piu mosso" b a b
+ \padText #1.8
+ c4^"piu mosso" d e f
+ \padText #2.6
+ c4^"piu mosso" fis a g
+}
+@end lilypond
+
+We can use it to create new commands,
+
+@lilypond[quote,verbatim,ragged-right]
+tempoMark = #(define-music-function (parser location padding marktext)
+ (number? string?)
+#{
+ \once \override Score . RehearsalMark #'padding = $padding
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
+ \mark \markup { \bold $marktext }
+#})
+
+\relative c'' {
+c2 e
+\tempoMark #3.0 #"Allegro"
+g c
+}
+@end lilypond
+
+Even music expressions can be passed in.
+
+@lilypond[quote,verbatim,ragged-right]
+pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
+#{
+ $x e8 a b $y b a e
+#})
+
+\relative c''{
+ \pattern c8 c8\f
+ \pattern {d16 dis} { ais16-> b\p }
+}
+@end lilypond
+
+
+@node Avoiding tweaks with slower processing
+@section Avoiding tweaks with slower processing
+
+LilyPond can perform extra checks while it processes files. These
+commands will take extra time, but the result may require fewer
+manual tweaks.
+
+@example
+%% makes sure text scripts and lyrics are within the paper margins
+\override Score.PaperColumn #'keep-inside-line = ##t
+@end example
+
-FIXME scheme stuffs