document new line-spanner.

diff --git a/Documentation/user/advanced-notation.itely b/Documentation/user/advanced-notation.itely
index 42cdb7bdae0f8a670720217f81e0be8b17cc7553..a35d81eb09708efa9b4c2398224c762d75163b02 100644 (file)
--- a/Documentation/user/advanced-notation.itely
+++ b/Documentation/user/advanced-notation.itely
@@ -40,6 +40,7 @@ saved as UTF-8.  For more information, see @ref{Text encoding}.
 
 @menu
 * Text scripts::                
+* Text and line spanners::      
 * Text spanners::               
 * Text marks::                  
 * Text markup::                 
@@ -105,6 +106,131 @@ In this manual: @ref{Text markup}.
 Program reference: @internalsref{TextScript}.
 
 
+@node Text and line spanners
+@subsection Text and line spanners
+
+Some performance indications, e.g., @i{rallentando} and
+@i{accelerando} and @i{trills} are written as text and are extended
+over many measures with lines, sometimes dotted or wavy.
+
+These all use the same routines as the glissando for drawing the texts
+and the lines, and tuning their behavior is therefore also done in the
+same way. It is done with a spanner, and the routine responsible for
+drawing the spanners is @code{ly:new-line-interface::print}. This
+routine creates determines the exact location of the two @i{span
+points} and draws a line in between, in the style requested.
+
+Here is an example of the different line styles available, and how to
+tune them.
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+d2 \glissando d'2
+\once \override Glissando #'dash-fraction = #0.5
+d,2 \glissando d'2
+\override Glissando #'style = #'dotted-line
+d,2 \glissando d'2
+\override Glissando #'style = #'zigzag
+d,2 \glissando d'2
+\override Glissando #'style = #'trill
+d,2 \glissando d'2
+@end lilypond
+
+The information that determines the end-points is computed on-the-fly
+for every graphic object, but it is possible to override these. 
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+e2 \glissando f
+\once \override Glissando #'bound-details #'right #'Y = #-2
+e2 \glissando f
+@end lilypond
+
+The @code{Glissando} object, like any other using the
+@code{ly:new-line-interface::print} routine, carries a nested
+association list. In the above statement, the @item value for @code{Y}
+is set to @code{-2} for association list corresponding to the right
+end point. Of course, it is also possible to adjust the left side with
+@code{left} instead of @code{right}.
+
+If @code{Y} is not set, the value is computed from the vertical
+position of right attachment point of the spanner. 
+
+In case of a line break, the values for the span-points are extended
+with contents of the @code{left-break} and @code{right-break}
+sublists, for example
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+\override Glissando #'breakable = ##T 
+\override Glissando #'bound-details #'right-break #'Y = #-3
+\override Glissando #'bound-details #'left-break #'Y = #3
+c1 \glissando \break
+f1
+@end lilypond
+
+The following properties can be used for the
+
+@table @code
+@item Y
+This sets the Y-coordinate of the end point, in staff space.  By
+default, it is the center of the bound object, so for a glissando it
+points to the vertical center of the note head.
+
+For horizontal spanners, such as text spanner and trill spanners, it
+is hardcoded to 0.
+
+@item attach-dir
+This determines where the line starts and ends in X-direction,
+relative to the bound object.  So, a value of @code{-1} (or
+@code{LEFT}) makes the line start/end at the left side of the note
+head it is attached to.
+
+@item X
+This is the absolute coordinate of the end point. It is usually
+computed on the fly, and there is little use in overriding it. 
+
+@item stencil
+Line spanners may have symbols at the beginning or end, which is
+contained in this sub-property.  This is for internal use, it is
+recommended to use @code{text}.
+
+@item text
+This is a markup that is evaluated to yield stencil. It is
+used to put @i{cresc.} and @i{tr} on horizontal spanners.
+
+@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
+\override TextSpanner #'bound-details #'left #'text
+   = \markup { \bold Slower }
+c2\startTextSpan b c\stopTextSpan a
+@end lilypond
+
+
+@item stencil-align-dir-y
+@item stencil-offset
+Without setting this, the stencil is simply put there at the
+end-point, as defined by the @code{X} and @code{Y} sub properties.
+Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
+will move the symbol at the edge relative to the end point of the line
+
+@lilypond[relative=1,fragment,verbatim]
+\override TextSpanner #'bound-details #'left #'stencil-align-dir-y = #DOWN
+\override TextSpanner #'bound-details #'right #'stencil-align-dir-y = #UP
+
+\override TextSpanner #'bound-details #'left #'text = #"gggg"
+\override TextSpanner #'bound-details #'right #'text = #"hhhh"
+c4^\startTextSpan c c c \stopTextSpan
+@end lilypond
+
+@item arrow
+Setting this sub property to @code{#t} produce an arrowhead at the end
+of the line.
+
+@item padding
+This sub property controls the space between the specified end-point
+of the line and the actual end.  Without padding, a glissando would
+start and end in the center of each note head.
+
+@end table
+
+
 @node Text spanners
 @subsection Text spanners