]> git.donarmstrong.com Git - lilypond.git/blobdiff - Documentation/user/text.itely
Merge branch 'master' of ssh://kainhofer@git.sv.gnu.org/srv/git/lilypond into kainhofer
[lilypond.git] / Documentation / user / text.itely
index a5899b535b6efb59b539b6af9bf0c9cfb13845c4..fe4464f894d58358112e4c06bc06785942c26a3e 100644 (file)
@@ -9,34 +9,21 @@
 @node Text
 @section Text
 
+@lilypondfile[quote]{text-headword.ly}
+
 This section explains how to include text (with various
 formatting) in your scores.
 
 @cindex Text, other languages
-To write accented and special text (such as characters from other
-languages), simply insert the characters directly into the
-lilypond file.  The file must be saved as UTF-8.  For more
-information, see @ref{Text encoding}.
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
+@warning{To write accented and special text (such as characters
+from other languages), simply insert the characters directly into
+the lilypond file.  The file must be saved as UTF-8.  For more
+information, see @ref{Text encoding}.}
 
 @menu
 * Writing text::                
 * Text markup::                 
+* Special text concerns::       
 @end menu
 
 
@@ -44,238 +31,145 @@ c'4^\markup { bla \bold bla }
 @subsection Writing text
 
 @menu
+* Overview of text entry::      
 * Text scripts::                
-* Text and line spanners::      
 * Text spanners::               
 * Text marks::                  
-* New dynamic marks::           
 @end menu
 
-@node Text scripts
-@unnumberedsubsubsec Text scripts
+@node Overview of text entry
+@subsubsection Overview of text entry
 
-@cindex Text scripts
-@cindex text items, non-empty
-@cindex non-empty texts
+There are four ways to add text to scores:
 
-It is possible to place arbitrary strings of text or @ref{Text
-markup}, above or below notes by using a string @code{c^"text"}.
-By default, these indications do not influence the note spacing,
-but by using the command @code{\fatText}, the widths will be taken
-into account
+@itemize
+@item
+@ref{Text scripts}: blah blah
 
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-c4^"longtext" \fatText c4_"longlongtext" c4
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c4^"text" c c c
 @end lilypond
 
-@noindent
-To prevent text from influencing spacing, use @code{\emptyText}.
-
-More complex formatting may also be added to a note by using the
-markup command,
+@item
+@ref{Text spanners}: blah blah
 
-@lilypond[fragment,ragged-right,verbatim,quote]
-c'4^\markup { bla \bold bla }
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c1
+\override TextSpanner #'bound-details #'left #'text =
+  \markup { \upright "rall" } 
+c2\startTextSpan b c\stopTextSpan a
 @end lilypond
 
-The @code{\markup} is described in more detail in @ref{Text
-markup}.
-
-
-@refcommands
+@item
+@ref{Text marks}: blah blah
 
-@funindex \fatText
-@code{\fatText},
-@funindex \emptyText
-@code{\emptyText}.
-
-
-@commonprop
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c4\mark "foo" c c c
+@end lilypond
 
-Checking to make sure that text scripts and lyrics are within the
-margins is a relatively large computational task.  To speed up
-processing, lilypond does not perform such calculations by
-default; to enable it, use
+@item
+@ref{Vocal music}: blah blah, not in this section.
 
-@example
-\override Score.PaperColumn #'keep-inside-line = ##t
-@end example
+@lilypond[verbatim,quote,ragged-right]
+<<
+  \relative c'' { c4 c c c }
+  \addlyrics { one two three four }
+>>
+@end lilypond
 
+@end itemize
 
 @seealso
 
-In this manual: @ref{Text markup}.
+Snippets: @lsrdir{Text,Text}
 
-Program reference: @internalsref{TextScript}.
 
 
-@node Text and line spanners
-@unnumberedsubsubsec 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.
+@node Text scripts
+@subsubsection Text scripts
 
-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:line-interface::print}.  This routine determines the
-exact location of the two @i{span points} and draws a line in
-between, in the style requested.
+@cindex Text scripts
+@cindex text items, non-empty
+@cindex non-empty texts
 
-Here is an example of the different line styles available, and how
-to tune them.
+It is possible to place arbitrary strings of text or @ref{Text
+markup} with @var{note}@code{-"}@var{text}@code{"}.
 
-@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
+INSERT EXAMPLE
 
-The information that determines the end-points is computed
-on-the-fly for every graphic object, but it is possible to
-override these. 
+More complex formatting may also be added to a note by using the
+@code{\markup} command, as described in @ref{Text markup}.
 
-@lilypond[relative=2,ragged-right,verbatim,fragment]
-e2 \glissando f
-\once \override Glissando #'bound-details #'right #'Y = #-2
-e2 \glissando f
+@lilypond[fragment,ragged-right,verbatim,quote]
+c'4^\markup { bla \bold bla }
 @end lilypond
 
-The @code{Glissando} object, like any other using the
-@code{ly:line-interface::print} routine, carries a nested
-association list.  In the above statement, the value for @code{Y}
-is set to @code{-2} for the 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-broken} and
-@code{right-broken} sublists, for example
-
-@lilypond[relative=2,ragged-right,verbatim,fragment]
-\override Glissando #'breakable = ##T 
-\override Glissando #'bound-details #'right-broken #'Y = #-3
-c1 \glissando \break
-f1
-@end lilypond
+@predefined
 
-The following properties can be used for the
+@funindex \textLengthOn
+@code{\textLengthOn},
+@funindex \textLengthOff
+@code{\textLengthOff}.
 
-@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.
+@snippets
+@c TODO: put this in the LSR. -vv
+By default, these indications do not influence the note spacing.
+However, by using the command @code{\textLengthOn}, the widths
+will be taken into account:
 
-@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=2,verbatim]
-\override TextSpanner #'bound-details #'left #'text
-   = \markup { \small \bold Slower }
-c2\startTextSpan b c a\stopTextSpan
-@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
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+c4^"this does not affect spacing" \textLengthOn c4_"whereas this does" c4
 @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.
+@noindent
+After having used such a command, to go back to the default behavior
+and prevent text from influencing spacing, use @code{\textLengthOff}.
 
-@end table
 
-TODO: add this somewhere
+@c TODO: LSR-ize this as well -vv
+Checking to make sure that text scripts and lyrics are within the
+margins is a relatively large computational task.  To speed up
+processing, lilypond does not perform such calculations by
+default; to enable it, use
 
-@verbatim
-\new Staff {
-  \override TextSpanner #'bound-details #'left-broken #'text = ##f
-   \override TextSpanner #'bound-details #'left #'text = \markup {
-"start" }
-   c'1 \startTextSpan \break
-   c'1
-   c'1 \stopTextSpan
-}
-@end verbatim
+@example
+\override Score.PaperColumn #'keep-inside-line = ##t
+@end example
 
 
 @seealso
 
-Program reference: @internalsref{TextSpanner},
-@internalsref{Glissando}, @internalsref{VoiceFollower},
-@internalsref{TrillSpanner},
-@internalsref{line-spanner-interface}.
+Notation Reference: @ref{Text markup}.
+
+Snippets: @lsrdir{Text,Text}
 
-Examples: @lsr{expressive,line-styles.ly},
-@lsr{expressive,line-arrows.ly}
+Internals Reference: @internalsref{TextScript}.
 
 
 @node Text spanners
-@unnumberedsubsubsec Text spanners
+@subsubsection Text spanners
 
 @cindex Text spanners
 
+@c TODO: merge these explanations with the ones below in 
+@c "Text and Line spanners" -vv
+
 Some performance indications, e.g., @i{rallentando} or
 @i{accelerando}, are written as text and are extended over many
 measures with dotted lines.  Such texts are created using text
 spanners; attach @code{\startTextSpan} and @code{\stopTextSpan} to
 the first and last notes of the spanner.
 
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c1
+\override TextSpanner #'bound-details #'left #'text = "faster" 
+c2\startTextSpan b c\stopTextSpan a
+@end lilypond
+
+@noindent
 The string to be printed, as well as the style, is set through
-object properties
+object properties. It can accept @code{\markup} blocks as well:
 
 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
 c1
@@ -290,7 +184,7 @@ c2\startTextSpan b c\stopTextSpan a
 c2\startTextSpan b c\stopTextSpan a
 @end lilypond
 
-@refcommands
+@predefined
 
 @funindex textSpannerUp
 @code{\textSpannerUp},
@@ -300,22 +194,24 @@ c2\startTextSpan b c\stopTextSpan a
 @code{\textSpannerNeutral}.
 
 
-@commonprop
+@snippets
 
 To print a solid line, use
 
 @example
-\override TextSpanner #'dash-fraction = #'()
+\override TextSpanner #'style = #'line
 @end example
 
 
 @seealso
 
-Program reference: @internalsref{TextSpanner}.
+Snippets: @lsrdir{Text,Text}
+
+Internals Reference: @internalsref{TextSpanner}.
 
 
 @node Text marks
-@unnumberedsubsubsec Text marks
+@subsubsection Text marks
 
 @cindex coda on bar line
 @cindex segno on bar line
@@ -324,9 +220,16 @@ Program reference: @internalsref{TextSpanner}.
 @funindex \mark
 
 The @code{\mark} command is primarily used for @ref{Rehearsal
-marks}, but it can also be used to put signs like coda, segno, and
-fermata on a bar line.  Use @code{\markup} to access the
-appropriate symbol (symbols are listed in @ref{The Feta font}).
+marks}, but it can also be used to add text elements in a score:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c4\mark "text" c c c
+@end lilypond
+
+As it can contain a @code{\markup} object, the @code{\mark} command
+makes possible to put any text, but also signs like coda, segno, or
+fermata on a bar line.  The appropriate symbol has to be specified in
+the @code{\markup} block; these symbols are listed in @ref{The Feta font}.
 
 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
@@ -334,7 +237,7 @@ c1
 @end lilypond
 
 @noindent
-@code{\mark} is only typeset above the top stave of the score.  If
+@code{\mark} is only typeset above the top staff of the score.  If
 you specify the @code{\mark} command at a bar line, the resulting
 mark is placed above the bar line.  If you specify it in the
 middle of a bar, the resulting mark is positioned between notes.
@@ -345,11 +248,14 @@ of the next line.
 
 @c  IMO this is a bug; hopefully it'll be fixed soon, so I can
 @c  delete this sentence.   -gp
+@noindent
 If there is no next line, then the mark will not be printed at
 all.
 
 
-@commonprop
+@snippets
+
+@c TODO: to be LSR-ized stuff -vv
 
 To print the mark at the end of the current line, use
 
@@ -402,7 +308,8 @@ Possible symbols for the @code{break-align-symbols} list are
 The text marks will, by default, be aligned with the middle of the
 notation object, but this can be changed by overriding the
 @code{break-align-anchor-alignment} and @code{break-align-anchor}
-properties for the appropriate grob.
+properties for the appropriate grob. For scores with multiple staves,
+this setting should be done for all the staves. 
 
 @lilypond[fragment,quote,ragged-right,verbatim]
 {
@@ -411,20 +318,20 @@ properties for the appropriate grob.
   \key cis \major
 
   % the RehearsalMark will be aligned with the left edge of the KeySignature
-  \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT
+  \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
   \mark \default
   cis1
   \key ces \major
 
   % the RehearsalMark will be aligned with the right edge of the KeySignature
-  \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT
+  \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
   \mark \default
   ces1
   \key cis \major
 
   % the RehearsalMark will be aligned with the left edge of the KeySignature
   % and then shifted right by 2 units.
-  \once \override Staff.KeySignature #'break-align-anchor = #2
+  \once \override Score.KeySignature #'break-align-anchor = #2
   \mark \default
   ces1
 }
@@ -454,47 +361,13 @@ staff, you may alter this to print them on every staff,
 
 @seealso
 
-Program reference: @internalsref{RehearsalMark}.
-
-
-
-@node New dynamic marks
-@unnumberedsubsubsec New dynamic marks
-
-It is possible to print new dynamic marks or text that should be
-aligned with dynamics.  Use @code{make-dynamic-script} to create
-these marks.  Note that the dynamic font only contains the
-characters @code{f,m,p,r,s} and @code{z}.
-
-Some situations (such as dynamic marks) have preset font-related
-properties.  If you are creating text in such situations, it is
-advisable to cancel those properties with @code{normal-text}.  See
-@ref{Overview of text markup commands}, for more details.
-
-@cindex make-dynamic-script
-
-@lilypond[quote,verbatim,ragged-right]
-sfzp = #(make-dynamic-script "sfzp")
-\relative c' {
-  c4 c c\sfzp c
-}
-@end lilypond
-
-@cindex Dynamics, editorial
-@cindex Dynamics, parenthesis
-
-It is also possible to print dynamics in round parenthesis or
-square brackets.  These are often used for adding editorial
-dynamics.
-
-@lilypond[quote,verbatim,ragged-right]
-rndf = \markup{ \center-align {\line { \bold{\italic (}
-  \dynamic f \bold{\italic )} }} }
-boxf = \markup{ \bracket { \dynamic f } }
-{ c'1_\rndf c'1_\boxf }
-@end lilypond
+Snippets: @lsrdir{Text,Text}
 
+Internals Reference: @internalsref{RehearsalMark}.
 
+@c TODO: add this here? -vv
+@c @node Text marks
+@c @subsubsection Text marks
 
 @node Text markup
 @subsection Text markup
@@ -507,7 +380,7 @@ boxf = \markup{ \bracket { \dynamic f } }
 @end menu
 
 @node Text markup introduction
-@unnumberedsubsubsec Text markup introduction
+@subsubsection Text markup introduction
 
 @cindex markup
 @cindex text markup
@@ -610,7 +483,7 @@ To keep lists of words distinct, please use quotes @code{"} or
 the @code{\line} command
 
 @lilypond[quote,verbatim,fragment,relative=1]
-\fatText
+\textLengthOn
 c4^\markup{ \center-align { on three lines } }
 c4^\markup{ \center-align { "all one line" } }
 c4^\markup{ \center-align { { on three lines } } }
@@ -638,7 +511,7 @@ markup, you need to use the #'padding property or create an
 #0}).
 
 @lilypond[quote,verbatim,fragment,relative=1]
-\fatText
+\textLengthOn
 c'4^\markup{ \raise #5 "not raised" }
 \once \override TextScript #'padding = #3
 c'4^\markup{ raised }
@@ -655,12 +528,14 @@ advisable to cancel those properties with @code{normal-text}.  See
 
 This manual: @ref{Overview of text markup commands}.
 
-Program reference: @internalsref{TextScript}.
+Snippets: @lsrdir{Text,Text}
+
+Internals Reference: @internalsref{TextScript}.
 
 Init files: @file{scm/@/new@/-markup@/.scm}.
 
 
-@refbugs
+@knownissues
 
 Kerning or generation of ligatures is only done when the @TeX{}
 backend is used.  In this case, LilyPond does not account for them
@@ -670,7 +545,7 @@ Syntax errors for markup mode are confusing.
 
 
 @node Nested scores
-@unnumberedsubsubsec Nested scores
+@subsubsection Nested scores
 
 It is possible to nest music inside markups, by adding a
 @code{\score} block to a markup expression.  Such a score must
@@ -688,8 +563,12 @@ contain a @code{\layout} block.
 }
 @end lilypond
 
+@seealso
+
+Snippets: @lsrdir{Text,Text}
+
 @node Page wrapping text
-@unnumberedsubsubsec Page wrapping text
+@subsubsection Page wrapping text
 
 Whereas @code{\markup} is used to enter a non-breakable block of
 text, @code{\markuplines} can be used at top-level to enter lines
@@ -719,13 +598,15 @@ lists.  The built-in markup list commands are described in
 This manual: @ref{Overview of text markup list commands}, @ref{New
 markup list command definition}.
 
-@refcommands
+Snippets: @lsrdir{Text,Text}
+
+@predefined
 
 @funindex \markuplines
 @code{\markuplines}
 
 @node Font selection
-@unnumberedsubsubsec Font selection
+@subsubsection Font selection
 
 @cindex font selection
 @cindex font magnification
@@ -739,7 +620,7 @@ Schoolbook, the sans and typewriter to whatever the Pango
 installation defaults to.
 
 
-@itemize @bullet
+@itemize
 @item @code{font-encoding}
 is a symbol that sets layout of the glyphs.  This should only be
 set to select different types of non-text fonts, e.g.
@@ -835,7 +716,236 @@ sans serif and monospaced text.  For example,
 
 @seealso
 
-Examples: @lsr{text,font@/-family@/-override.ly}.
+Snippets: @lsrdir{Text,Text}
+
+
+@node Special text concerns
+@subsection Special text concerns
+
+@c FIXME: this section is to be removed
+@c (see comments below) -vv
+
+@menu
+* New dynamic marks::           
+* Text and line spanners::      
+@end menu
+
+@node New dynamic marks
+@subsubsection New dynamic marks
+
+@c FIXME: this whole section should be removed and put in
+@c "Writing text" -vv
+
+It is possible to print new dynamic marks or text that should be
+aligned with dynamics.  Use @code{make-dynamic-script} to create
+these marks.  Note that the dynamic font only contains the
+characters @code{f,m,p,r,s} and @code{z}.
+
+Some situations (such as dynamic marks) have preset font-related
+properties.  If you are creating text in such situations, it is
+advisable to cancel those properties with @code{normal-text}.  See
+@ref{Overview of text markup commands}, for more details.
+
+@cindex make-dynamic-script
+
+@lilypond[quote,verbatim,ragged-right]
+sfzp = #(make-dynamic-script "sfzp")
+\relative c' {
+  c4 c c\sfzp c
+}
+@end lilypond
+
+@cindex Dynamics, editorial
+@cindex Dynamics, parenthesis
+
+It is also possible to print dynamics in round parenthesis or
+square brackets.  These are often used for adding editorial
+dynamics.
+
+@lilypond[quote,verbatim,ragged-right]
+rndf = \markup{ \center-align {\line { \bold{\italic (}
+  \dynamic f \bold{\italic )} }} }
+boxf = \markup{ \bracket { \dynamic f } }
+{ c'1_\rndf c'1_\boxf }
+@end lilypond
+
+@seealso
+
+Snippets: @lsrdir{Text,Text}
+
+
+@node Text and line spanners
+@subsubsection Text and line spanners
+
+@c FIXME: this whole section has to be removed.
+@c glissando stuff should go into Expressive marks;
+@c Text spanners should go into... Text spanners.
+@c (I'm on it) --vv
+
+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:line-interface::print}.  This routine 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 #'style = #'dashed-line
+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:line-interface::print} routine, carries a nested
+association list.  In the above statement, the value for @code{Y}
+is set to @code{-2} for the 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-broken} and
+@code{right-broken} sublists, for example
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+\override Glissando #'breakable = ##T 
+\override Glissando #'bound-details #'right-broken #'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=2,verbatim]
+\override TextSpanner #'bound-details #'left #'text
+   = \markup { \small \bold Slower }
+c2\startTextSpan b c a\stopTextSpan
+@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
+
+TODO: add this somewhere
+
+@verbatim
+\new Staff {
+  \override TextSpanner #'bound-details #'left-broken #'text = ##f
+   \override TextSpanner #'bound-details #'left #'text = \markup {
+"start" }
+   c'1 \startTextSpan \break
+   c'1
+   c'1 \stopTextSpan
+}
+@end verbatim
+
+
+The music function \endSpanners terminates spanners and hairpins
+after exactly one note.
+
+@lilypond[verbatim,quote,ragged-right,relative=2,fragment]
+\endSpanners
+c2 \startTextSpan c2
+c2 \< c2
+@end lilypond
+
+When using \endSpanners it is not necessary to close
+\startTextSpan with \stopTextSpan, nor is it necessary to close
+hairpins with \!.
+
+
+
+@seealso
+
+Snippets: @lsrdir{Text,Text}
+
+Internals Reference: @internalsref{TextSpanner},
+@internalsref{Glissando}, @internalsref{VoiceFollower},
+@internalsref{TrillSpanner},
+@internalsref{line-spanner-interface}.
+