X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=Documentation%2Fuser%2Ftweaks.itely;h=27b74e1fc21f45c9e425674c59f561b9bb664d8a;hb=38cb4178d57c3d964f5e4187be34d7372b4a646b;hp=0df2567f3a003b9aff339502a5667dbc3441a2dd;hpb=662c715cc4b57eeb4ec4da21e40a6d839e4368c3;p=lilypond.git

diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely
index 0df2567f3a..27b74e1fc2 100644
--- a/Documentation/user/tweaks.itely
+++ b/Documentation/user/tweaks.itely
@@ -2,22 +2,25 @@
 @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::  
+* 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.
 
@@ -59,7 +62,7 @@ c4^"piu mosso" d e f
 \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
@@ -72,7 +75,8 @@ Another solution gives us complete control over placing the object -- we
 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]
@@ -124,12 +128,54 @@ c4^"piu mosso" d e f
 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
 
@@ -140,13 +186,15 @@ 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
+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}.
@@ -170,15 +218,17 @@ d1
 
 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.
@@ -190,11 +240,11 @@ the left, and 1.8 staff space downwards:
 \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
@@ -220,6 +270,7 @@ voice.  By introducing a tie in a different voice,
 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
@@ -229,6 +280,20 @@ voices:
 } >>
 @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
@@ -237,7 +302,7 @@ voices:
 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.
 
 
@@ -256,17 +321,17 @@ 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
+@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
 
@@ -275,16 +340,104 @@ particular interest.  Files such as @file{ly/property-init.ly} and
 @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?)
@@ -304,24 +457,22 @@ 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?)
@@ -335,3 +486,18 @@ 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
+
+
+