Doc-de: update macros.itely and nitpicks

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

diff --git a/Documentation/user/tweaks.itely b/Documentation/user/tweaks.itely
index 24a488f31e2084ca39343b0adf94e19938d1619d..c0a6e72af90c16228344db8752d83f9ead97f49a 100644 (file)
--- a/Documentation/user/tweaks.itely
+++ b/Documentation/user/tweaks.itely
@@ -7,7 +7,7 @@
     version that you are working on.  See TRANSLATION for details.
 @end ignore
 
-@c \version "2.11.65"
+@c \version "2.12.0"
 
 @node Tweaking output
 @chapter Tweaking output
@@ -369,11 +369,12 @@ Note that the syntax of @code{\tweak} is different from that
 of the @code{\override} command.  Neither the context nor the
 layout object should be specified; in fact, it would generate
 an error to do so.  These are both implied by the following
-item in the input stream.  So the general syntax of the
+item in the input stream.  Note also that an equals sign should
+not be present.  So the general syntax of the
 @code{\tweak} command is simply
 
 @example
-\tweak #'@var{layout-property} = #@var{value}
+\tweak #'@var{layout-property} #@var{value}
 @end example
 
 A @code{\tweak} command can also be used to modify just one in
@@ -1052,6 +1053,22 @@ it by adding the correct context:
 
 Now the bar lines have vanished.
 
+Note, though, that setting the @code{stencil} property to @code{#f}
+will cause errors when the dimensions of the object are required for
+correct processing.  For example, errors will be generated if the
+@code{stencil} property of the @code{NoteHead} object is set to
+@code{#f}.  If this is the case, you can instead use the
+@code{point-stencil} function, which sets the stencil to a object
+with zero size:
+
+@lilypond[quote,verbatim,relative=2]
+{
+  c c
+  \once \override NoteHead #'stencil = #point-stencil
+  c c
+}
+@end lilypond
+
 @subheading break-visibility
 
 @cindex break-visibility property
@@ -1303,7 +1320,7 @@ how to introduce a new temporary staff, as in an @rglos{ossia}.
          <<
            { f c c }
            \new Staff \with {
-             alignAboveContext = "main" }
+             alignAboveContext = #"main" }
            { f8 f c }
          >>
          r4 |
@@ -1330,7 +1347,7 @@ we simply set the stencil of each to @code{#f}, as follows:
     <<
       { f c c }
       \new Staff \with {
-        alignAboveContext = "main"
+        alignAboveContext = #"main"
       }
       {
         \override Staff.Clef #'stencil = ##f
@@ -1391,7 +1408,7 @@ So we could replace the example above with
     <<
       { f c c }
       \new Staff \with {
-        alignAboveContext = "main"
+        alignAboveContext = #"main"
         % Don't print clefs in this staff
         \override Clef #'stencil = ##f
         % Don't print time signatures in this staff
@@ -1455,7 +1472,7 @@ Let's try it in our ossia example:
     <<
       { f c c }
       \new Staff \with {
-        alignAboveContext = "main"
+        alignAboveContext = #"main"
         \override Clef #'stencil = ##f
         \override TimeSignature #'stencil = ##f
         % Reduce all font sizes by ~24%
@@ -1520,7 +1537,7 @@ objects in proportion.  It is used like this:
     <<
       { f c c }
       \new Staff \with {
-        alignAboveContext = "main"
+        alignAboveContext = #"main"
         \override Clef #'stencil = ##f
         \override TimeSignature #'stencil = ##f
         fontSize = #-2
@@ -1807,7 +1824,7 @@ notes of a chord, as shown:
 @end lilypond
 
 @noindent
-but this may be overriden to manually force all or any of the
+but this may be overridden to manually force all or any of the
 individual fingering numbers above or below:
 
 @cindex fingering example
@@ -2048,6 +2065,33 @@ c\ff c \stopTextSpan
 c, c c c
 @end lilypond
 
+@cindex slurs and outside-staff-priority
+@cindex slurs and articulations
+@cindex articulations and slurs
+
+Slurs by default are classed as within-staff objects, but
+they often appear above the staff if the notes to
+which they are attached are high on the staff.  This can push
+outside-staff objects such as articulations too high, as the slur
+will be placed first.  The @code{avoid-slur} property of the
+articulation can be set to @code{'inside} to bring the articulation
+inside the slur, but the @code{avoid-slur} property is effective
+only if the @code{outside-staff-priority} is also set to @code{#f}.
+Alternatively, the @code{outside-staff-priority} of the slur
+can be set to a numerical value to cause it to be placed along with
+other outside-staff objects according to that value.  Here's an
+example showing the effect of the two methods:
+
+@lilypond[quote,verbatim,relative=2]
+c4( c^\markup\tiny\sharp d4.) c8
+c4(
+\once \override TextScript #'avoid-slur = #'inside
+\once \override TextScript #'outside-staff-priority = ##f
+c^\markup\tiny\sharp d4.) c8
+\once \override Slur #'outside-staff-priority = #500
+c4( c^\markup\tiny\sharp d4.) c8
+@end lilypond
+
 Changing the @code{outside-staff-priority} can also be used to
 control the vertical placement of individual objects, although
 the results may not always be desirable.  Suppose we would