@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
-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 @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
-@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
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
} >>
@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 @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.
+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
projects / lilypond.git / blobdiff