@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::
+* Fitting music onto fewer pages::
+* 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.
\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]
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 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
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
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
+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=2,verbatim]
+<< {
+ \once \override Stem #'transparent = ##t
+ \once \override Stem #'length = #8
+ b8~ b8\noBeam
+} \\ {
+ b[ g8]
+} >>
+@end lilypond
+
@end itemize
@cindex Tweaks, 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.
a substantial amount of technical knowledge or time is required
to understand these files.
-@itemize bullet
+@itemize @bullet
-@item Linux: @file{@{INSTALLDIR@}/lilypond/usr/share/lilypond/current/}
+@item Linux: @file{@var{installdir}/lilypond/usr/share/lilypond/current/}
@item OSX:
-@file{@{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".
+@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{@{INSTALLDIR@}/LilyPond/usr/share/lilypond/current/}
+@item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}
@end itemize
@file{ly/declarations-init.ly} define all the common tweaks.
-@node Advanced tweaks with scheme
-@section Advanced tweaks with scheme
+@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. 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?)
projects / lilypond.git / blobdiff