@c -*- coding: utf-8; mode: texinfo; -*-
+@c This file is part of lilypond.tely
+@ignore
+ Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
+
+ When revising a translation, copy the HEAD committish of the
+ version that you are working on. See TRANSLATION for details.
+@end ignore
+
@node Tweaking output
@chapter Tweaking output
@menu
+* Moving objects::
* Fixing overlapping notation::
* Common tweaks::
* Default files::
-* Advanced tweaks with scheme::
+* 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 is not perfect. Some notation
elements can overlap. This is unfortunate, but (in most cases) is easily
\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
+the movement is done after LilyPond has placed all other objects. This
means
that the result can overlap with other objects.
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 @q{@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
@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}.
@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
@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
+in @q{invisible ink}: the object is not printed, but all its other
behavior is retained. The object still takes up space, it takes part in
collisions, and slurs, ties, and beams can be attached to it.
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
+ b8~ b8\noBeam
+} \\ {
+ b[ g8]
+} >>
+@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]
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 @q{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
+ \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
\mark \markup { \bold $marktext }
#})
\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?)
}
@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
+
+
+