Merge branch 'master' of ssh+git://git.sv.gnu.org/srv/git/lilypond

[lilypond.git] / Documentation / user / tweaks.itely

diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely
index fb1bdea8ef819021e283df801dd52e8301089f41..6d24d3a4225f396c2e5434c3c823690c88a3038d 100644 (file)
--- a/Documentation/user/tweaks.itely
+++ b/Documentation/user/tweaks.itely
@@ -1,4 +1,12 @@
 @c -*- coding: utf-8; mode: texinfo; -*-
 @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
 
 @node Tweaking output
 @chapter Tweaking output
 


@@ -13,6 +21,7 @@ configurable; virtually every fragment of output may be changed.
 * Default files::               
 * Fitting music onto fewer pages::  
 * Advanced tweaks with Scheme::  
 * Default files::               
 * Fitting music onto fewer pages::  
 * Advanced tweaks with Scheme::  

+* Avoiding tweaks with slower processing::  

 @end menu
 
 
 @end menu
 
 


@@ -23,7 +32,16 @@ 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.
 
 elements can overlap.  This is unfortunate, but (in most cases) is easily
 solved.
 

+@c  FIXME: find a better example for 5.1 Moving Objects.  -gp
+@c  yes, I want this TODO to be visible to end-users.  It's better
+@c  than having nothing at all.
+TODO: with the new spacing features in 2.12, these specific examples are no
+longer relevant.  However, they still demonstrate powerful features
+of lilypond, so they remain until somebody creates some better examples.
+

 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]

+  % temporary code to break this example:
+  \override TextScript #'outside-staff-priority = ##f

 e4^\markup{ \italic ritenuto } g b e
 @end lilypond
 
 e4^\markup{ \italic ritenuto } g b e
 @end lilypond
 


@@ -37,6 +55,8 @@ objects, this value is around 1.0 or less (it varies with each
 object). We want to increase it, so let's try 1.5
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
 object). We want to increase it, so let's try 1.5
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]

+  % temporary code to break this example:
+  \override TextScript #'outside-staff-priority = ##f

 \once \override TextScript #'padding = #1.5
 e4^\markup{ \italic ritenuto } g b e
 @end lilypond
 \once \override TextScript #'padding = #1.5
 e4^\markup{ \italic ritenuto } g b e
 @end lilypond


@@ -55,16 +75,18 @@ object and the staff.  This is a subtle difference, but you can see
 the behavior here.
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
 the behavior here.
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]

+  % temporary code to break this example:
+  \override TextScript #'outside-staff-priority = ##f

 c4^"piu mosso" b a b
 c4^"piu mosso" b a b

-\once \override TextScript #'padding = #2.6
+\once \override TextScript #'padding = #4.6

 c4^"piu mosso" d e f
 c4^"piu mosso" d e f

-\once \override TextScript #'staff-padding = #2.6
+\once \override TextScript #'staff-padding = #4.6

 c4^"piu mosso" fis a g
 \break
 c'4^"piu mosso" b a b
 c4^"piu mosso" fis a g
 \break
 c'4^"piu mosso" b a b

-\once \override TextScript #'padding = #2.6
+\once \override TextScript #'padding = #4.6

 c4^"piu mosso" d e f
 c4^"piu mosso" d e f

-\once \override TextScript #'staff-padding = #2.6
+\once \override TextScript #'staff-padding = #4.6

 c4^"piu mosso" fis a g
 @end lilypond
 
 c4^"piu mosso" fis a g
 @end lilypond
 


@@ -79,6 +101,8 @@ means
 that the result can overlap with other objects.
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
 that the result can overlap with other objects.
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]

+  % temporary code to break this example:
+  \override TextScript #'outside-staff-priority = ##f

 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
 e4^\markup{ \italic ritenuto } g b e
 @end lilypond
 \once \override TextScript #'extra-offset = #'( 1.0 . -1.0 )
 e4^\markup{ \italic ritenuto } g b e
 @end lilypond


@@ -89,6 +113,8 @@ movement (up is positive).  After a bit of experimenting, we decided
 that these values look good
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]
 that these values look good
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=2]

+  % temporary code to break this example:
+  \override TextScript #'outside-staff-priority = ##f

 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
 e4^\markup{ \italic ritenuto } g b e
 @end lilypond
 \once \override TextScript #'extra-offset = #'( -1.6 . 1.0 )
 e4^\markup{ \italic ritenuto } g b e
 @end lilypond


@@ -112,15 +138,17 @@ the command, omit the @code{\once}.  To stop this tweak, use a
 @ref{The \override command}.
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]
 @ref{The \override command}.
 
 @lilypond[quote,fragment,ragged-right,verbatim,relative=3]

+  % temporary code to break this example:
+  \override TextScript #'outside-staff-priority = ##f

 c4^"piu mosso" b
 c4^"piu mosso" b

-\once \override TextScript #'padding = #2.6
+\once \override TextScript #'padding = #4.6

   a4 b
 c4^"piu mosso" d e f
   a4 b
 c4^"piu mosso" d e f

-\once \override TextScript #'padding = #2.6
+\once \override TextScript #'padding = #4.6

 c4^"piu mosso" d e f
 c4^"piu mosso" d e f
 \break
 c4^"piu mosso" d e f
 c4^"piu mosso" d e f
 \break

-\override TextScript #'padding = #2.6
+\override TextScript #'padding = #4.6

 c4^"piu mosso" d e f
 c4^"piu mosso" d e f
 \revert TextScript #'padding
 c4^"piu mosso" d e f
 c4^"piu mosso" d e f
 \revert TextScript #'padding


@@ -140,7 +168,7 @@ object.  The same mechanism can be used to move other types of
 objects; simply replace @code{TextScript} with the name of
 another object.
 
 objects; simply replace @code{TextScript} with the name of
 another object.
 

-To find the object name, look at the ``@strong{see also}'' at
+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
 
 bottom of the relevant documentation page.  For example, at
 the bottom of @ref{Dynamics}, we see
 


@@ -243,9 +271,9 @@ f-5
 f-5
 @end lilypond
 
 f-5
 @end lilypond
 

- @item
+@item

 Setting the @code{transparent} property will cause an object to be printed
 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.
 
 behavior is retained.  The object still takes up space, it takes part in
 collisions, and slurs, ties, and beams can be attached to it.
 


@@ -269,6 +297,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:
 
 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
 @lilypond[quote,fragment,relative=2,verbatim]
 << {
   \once \override Stem #'transparent = ##t


@@ -278,6 +307,20 @@ voices:
 } >>
 @end lilypond
 
 } >>
 @end lilypond
 

+To make sure that the just blanked stem doesn't squeeze 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
 @end itemize
 
 @cindex Tweaks, distances


@@ -307,15 +350,15 @@ 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:
 
 @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
+@q{Show Package Contents}.

 
 

-@item Windows: @file{@{INSTALLDIR@}/LilyPond/usr/share/lilypond/current/}
+@item Windows: @file{@var{installdir}/LilyPond/usr/share/lilypond/current/}

 
 @end itemize
 
 
 @end itemize
 


@@ -349,10 +392,10 @@ space at the bottom of the page.
 
 @example
 \paper @{
 
 @example
 \paper @{

-between-system-padding = #0.5
-between-system-space = 0\mm
-ragged-last-bottom = ##f
-ragged-bottom = ##f
+  between-system-padding = #0.1
+  between-system-space = #0.1
+  ragged-last-bottom = ##f
+  ragged-bottom = ##f

 @}
 @end example
 
 @}
 @end example
 


@@ -363,7 +406,7 @@ use 10).
 
 @example
 \paper @{
 
 @example
 \paper @{

-system-count = #10
+  system-count = #10

 @}
 @end example
 
 @}
 @end example
 


@@ -374,7 +417,7 @@ 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.
 
 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
+Another example is moving dynamics which @q{stick out} of

 a system.
 
 @lilypond[verbatim,quote,fragment]
 a system.
 
 @lilypond[verbatim,quote,fragment]


@@ -445,14 +488,14 @@ tempoMark = #(define-music-function (parser location padding marktext)
                                     (number? string?)
 #{
   \once \override Score . RehearsalMark #'padding = $padding
                                     (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'' {
   \mark \markup { \bold $marktext }
 #})
 
 \relative c'' {

-c2 e
-\tempoMark #3.0 #"Allegro"
-g c
+  c2 e
+  \tempoMark #3.0 #"Allegro"
+  g c

 }
 @end lilypond
 
 }
 @end lilypond
 


@@ -470,3 +513,18 @@ pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
 }
 @end lilypond
 
 }
 @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
+
+
+