]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/text.itely
Clarify that break-align-anchor-alignment has to be set for
[lilypond.git] / Documentation / user / text.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @ignore
3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
4
5     When revising a translation, copy the HEAD committish of the
6     version that you are working on.  See TRANSLATION for details.
7 @end ignore
8
9 @node Text
10 @section Text
11
12 @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
13 {text-headword.ly}
14
15 This section explains how to include text (with various
16 formatting) in your scores.
17
18 @cindex Text, other languages
19 To write accented and special text (such as characters from other
20 languages), simply insert the characters directly into the
21 lilypond file.  The file must be saved as UTF-8.  For more
22 information, see @ref{Text encoding}.
23
24 @menu
25 * Writing text::                
26 * Text markup::                 
27 * Special text concerns::       
28 @end menu
29
30
31 @node Writing text
32 @subsection Writing text
33
34 @menu
35 * Overview of text entry::      
36 * Text scripts::                
37 * Text spanners::               
38 * Text marks::                  
39 @end menu
40
41 @node Overview of text entry
42 @subsubsection Overview of text entry
43
44 There are four ways to add text to scores:
45
46 @itemize
47 @item
48 @ref{Text scripts}: blah blah
49
50 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
51 c4^"text" c c c
52 @end lilypond
53
54 @item
55 @ref{Text spanners}: blah blah
56
57 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
58 c1
59 \override TextSpanner #'bound-details #'left #'text =
60   \markup { \upright "rall" } 
61 c2\startTextSpan b c\stopTextSpan a
62 @end lilypond
63
64 @item
65 @ref{Text marks}: blah blah
66
67 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
68 c4\mark "foo" c c c
69 @end lilypond
70
71 @item
72 @ref{Vocal music}: blah blah, not in this section.
73
74 @lilypond[verbatim,quote,ragged-right]
75 <<
76   \relative c'' { c4 c c c }
77   \addlyrics { one two three four }
78 >>
79 @end lilypond
80
81 @end itemize
82
83 @seealso
84
85 Snippets: @lsrdir{Text,Text}
86
87
88
89 @node Text scripts
90 @subsubsection Text scripts
91
92 @cindex Text scripts
93 @cindex text items, non-empty
94 @cindex non-empty texts
95
96 It is possible to place arbitrary strings of text or @ref{Text
97 markup}, above or below notes by using a string @code{c^"text"}.
98 By default, these indications do not influence the note spacing,
99 but by using the command @code{\textLengthOn}, the widths will be taken
100 into account
101
102 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
103 c4^"longtext" \textLengthOn c4_"longlongtext" c4
104 @end lilypond
105
106 @noindent
107 To prevent text from influencing spacing, use @code{\textLengthOff}.
108
109 More complex formatting may also be added to a note by using the
110 markup command,
111
112 @lilypond[fragment,ragged-right,verbatim,quote]
113 c'4^\markup { bla \bold bla }
114 @end lilypond
115
116 The @code{\markup} is described in more detail in @ref{Text
117 markup}.
118
119
120 @refcommands
121
122 @funindex \textLengthOn
123 @code{\textLengthOn},
124 @funindex \textLengthOff
125 @code{\textLengthOff}.
126
127
128 @commonprop
129
130 Checking to make sure that text scripts and lyrics are within the
131 margins is a relatively large computational task.  To speed up
132 processing, lilypond does not perform such calculations by
133 default; to enable it, use
134
135 @example
136 \override Score.PaperColumn #'keep-inside-line = ##t
137 @end example
138
139
140 @seealso
141
142 Notation Reference: @ref{Text markup}.
143
144 Snippets: @lsrdir{Text,Text}
145
146 Internals Reference: @internalsref{TextScript}.
147
148
149 @node Text spanners
150 @subsubsection Text spanners
151
152 @cindex Text spanners
153
154 Some performance indications, e.g., @i{rallentando} or
155 @i{accelerando}, are written as text and are extended over many
156 measures with dotted lines.  Such texts are created using text
157 spanners; attach @code{\startTextSpan} and @code{\stopTextSpan} to
158 the first and last notes of the spanner.
159
160 The string to be printed, as well as the style, is set through
161 object properties
162
163 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
164 c1
165 \textSpannerDown
166 \override TextSpanner #'bound-details #'left #'text =
167   \markup { \upright "rall" } 
168 c2\startTextSpan b c\stopTextSpan a
169 \break
170 \textSpannerUp
171 \override TextSpanner #'bound-details #'left #'text =
172   \markup { \italic "rit" } 
173 c2\startTextSpan b c\stopTextSpan a
174 @end lilypond
175
176 @refcommands
177
178 @funindex textSpannerUp
179 @code{\textSpannerUp},
180 @funindex textSpannerDown
181 @code{\textSpannerDown},
182 @funindex textSpannerNeutral
183 @code{\textSpannerNeutral}.
184
185
186 @commonprop
187
188 To print a solid line, use
189
190 @example
191 \override TextSpanner #'style = #'line
192 @end example
193
194
195 @seealso
196
197 Snippets: @lsrdir{Text,Text}
198
199 Internals Reference: @internalsref{TextSpanner}.
200
201
202 @node Text marks
203 @subsubsection Text marks
204
205 @cindex coda on bar line
206 @cindex segno on bar line
207 @cindex fermata on bar line
208 @cindex bar lines, symbols on
209 @funindex \mark
210
211 The @code{\mark} command is primarily used for @ref{Rehearsal
212 marks}, but it can also be used to put signs like coda, segno, and
213 fermata on a bar line.  Use @code{\markup} to access the
214 appropriate symbol (symbols are listed in @ref{The Feta font}).
215
216 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
217 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
218 c1
219 @end lilypond
220
221 @noindent
222 @code{\mark} is only typeset above the top stave of the score.  If
223 you specify the @code{\mark} command at a bar line, the resulting
224 mark is placed above the bar line.  If you specify it in the
225 middle of a bar, the resulting mark is positioned between notes.
226 If it is specified before the beginning of a score line, it is
227 placed before the first note of the line.  Finally, if the mark
228 occurs at a line break, the mark will be printed at the beginning
229 of the next line.
230
231 @c  IMO this is a bug; hopefully it'll be fixed soon, so I can
232 @c  delete this sentence.   -gp
233 If there is no next line, then the mark will not be printed at
234 all.
235
236
237 @commonprop
238
239 To print the mark at the end of the current line, use
240
241 @example
242 \override Score.RehearsalMark
243   #'break-visibility = #begin-of-line-invisible
244 @end example
245
246 @code{\mark} is often useful for adding text to the end of bar.
247 In such cases, changing the @code{#'self-alignment} is very useful
248
249 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
250 \override Score.RehearsalMark
251   #'break-visibility = #begin-of-line-invisible
252 c1 c c c4 c c c
253 \once \override Score.RehearsalMark #'self-alignment-X = #right
254 \mark "D.S. al Fine "
255 @end lilypond
256
257 Text marks may be aligned with notation objects other than bar
258 lines,
259
260 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
261 \relative {
262   c1
263   \key cis \major
264   \clef alto
265   \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
266   \mark "on key"
267   cis
268   \key ces \major
269   \override Score.RehearsalMark #'break-align-symbols = #'(clef)
270   \clef treble
271   \mark "on clef"
272   ces
273   \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
274   \key d \minor
275   \clef tenor
276   \time 3/4
277   \mark "on time"
278   c
279 }
280 @end lilypond
281
282 Possible symbols for the @code{break-align-symbols} list are
283 @code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
284 @code{staff-bar}, @code{left-edge}, @code{key-cancellation},
285 @code{key-signature}, and @code{time-signature}.
286
287 The text marks will, by default, be aligned with the middle of the
288 notation object, but this can be changed by overriding the
289 @code{break-align-anchor-alignment} and @code{break-align-anchor}
290 properties for the appropriate grob. For scores with multiple staves,
291 this setting should be done for all the staves. 
292
293 @lilypond[fragment,quote,ragged-right,verbatim]
294 {
295   \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
296   c1
297   \key cis \major
298
299   % the RehearsalMark will be aligned with the left edge of the KeySignature
300   \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
301   \mark \default
302   cis1
303   \key ces \major
304
305   % the RehearsalMark will be aligned with the right edge of the KeySignature
306   \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
307   \mark \default
308   ces1
309   \key cis \major
310
311   % the RehearsalMark will be aligned with the left edge of the KeySignature
312   % and then shifted right by 2 units.
313   \once \override Score.KeySignature #'break-align-anchor = #2
314   \mark \default
315   ces1
316 }
317 @end lilypond
318
319 Although text marks are normally only printed above the topmost
320 staff, you may alter this to print them on every staff,
321
322 @lilypond[quote,ragged-right,verbatim,relative=2]
323 {
324   \new Score \with {
325     \remove "Mark_engraver"
326   }
327   <<
328     \new Staff \with {
329       \consists "Mark_engraver"
330     }
331     { c''1 \mark "foo" c'' }
332     \new Staff \with {
333       \consists "Mark_engraver"
334     }
335     { c'1 \mark "foo" c' }
336   >>
337 }
338 @end lilypond
339
340
341 @seealso
342
343 Snippets: @lsrdir{Text,Text}
344
345 Internals Reference: @internalsref{RehearsalMark}.
346
347
348
349 @node Text markup
350 @subsection Text markup
351
352 @menu
353 * Text markup introduction::    
354 * Nested scores::               
355 * Page wrapping text::          
356 * Font selection::              
357 @end menu
358
359 @node Text markup introduction
360 @subsubsection Text markup introduction
361
362 @cindex markup
363 @cindex text markup
364 @cindex markup text
365 @cindex typeset text
366
367 Use @code{\markup} to typeset text.  Commands are entered with the
368 backslash @code{\}.  To enter @code{\} and @code{#}, use double
369 quotation marks.
370
371 @lilypond[quote,verbatim,fragment,relative=1]
372 c1^\markup { hello }
373 c1_\markup { hi there }
374 c1^\markup { hi \bold there, is \italic {anyone home?} }
375 c1_\markup { "\special {weird} #characters" }
376 @end lilypond
377
378 @noindent
379 See @ref{Overview of text markup commands}, for a list of all
380 commands.
381
382 @code{\markup} is primarily used for @internalsref{TextScript}s,
383 but it can also be used anywhere text is called in lilypond
384
385 @lilypond[quote,verbatim]
386 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
387 \score{
388   \relative c'' {
389     \override Score.RehearsalMark
390       #'break-visibility = #begin-of-line-invisible
391     \override Score.RehearsalMark #'self-alignment-X = #right
392
393     \set Staff.instrumentName = \markup{ \column{ Alto solo } }
394     c2^\markup{ don't be \flat }
395     \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
396     b2\startTextSpan
397     a2\mark \markup{ \large \bold Fine }
398     r2\stopTextSpan
399     \bar "||"
400   }
401   \addlyrics { bar, foo \markup{ \italic bar! } }
402 }
403 @end lilypond
404
405 A @code{\markup} command can also be placed on its own, away from
406 any @code{\score} block, see @ref{Multiple scores in a book}.
407
408 @lilypond[quote,ragged-right,verbatim]
409 \markup{ Here is some text. }
410 @end lilypond
411
412 @cindex font switching
413
414 The markup in the example demonstrates font switching commands.
415 The command @code{\bold} and @code{\italic} apply to the first
416 following word only; to apply a command to more than one word,
417 enclose the words with braces,
418
419 @example
420 \markup @{ \bold @{ hi there @} @}
421 @end example
422
423 @noindent
424 For clarity, you can also do this for single arguments, e.g.,
425
426 @example
427 \markup @{ is \italic @{ anyone @} home @}
428 @end example
429
430 In markup mode you can compose expressions, similar to
431 mathematical expressions, XML documents, and music expressions.
432 You can stack expressions grouped vertically with the command
433 @code{\column}.  Similarly, @code{\center-align} aligns texts by
434 their center lines:
435
436 @lilypond[quote,verbatim,fragment,relative=1]
437 c1^\markup { \column { a bbbb \line { c d } } }
438 c1^\markup { \center-align { a bbbb c } }
439 c1^\markup { \line { a b c } }
440 @end lilypond
441
442 Lists with no previous command are not kept distinct.  The
443 expression
444
445 @example
446 \center-align @{ @{ a b @} @{ c d @} @}
447 @end example
448
449 @noindent
450
451 is equivalent to
452
453 @example
454 \center-align @{ a b c d @}
455 @end example
456
457 @noindent
458
459 To keep lists of words distinct, please use quotes @code{"} or
460 the @code{\line} command
461
462 @lilypond[quote,verbatim,fragment,relative=1]
463 \textLengthOn
464 c4^\markup{ \center-align { on three lines } }
465 c4^\markup{ \center-align { "all one line" } }
466 c4^\markup{ \center-align { { on three lines } } }
467 c4^\markup{ \center-align { \line { on one line } } }
468 @end lilypond
469
470 Markups can be stored in variables and these variables may be
471 attached to notes, like
472
473 @example
474 allegro = \markup @{ \bold \large @{ Allegro @} @}
475  @{ a^\allegro b c d @}
476 @end example
477
478 Some objects have alignment procedures of their own, which cancel
479 out any effects of alignments applied to their markup arguments as
480 a whole.  For example, the @internalsref{RehearsalMark} is
481 horizontally centered, so using @code{\mark \markup @{ \left-align
482 .. @}} has no effect.
483
484 In addition, vertical placement is performed after creating the
485 text markup object.  If you wish to move an entire piece of
486 markup, you need to use the #'padding property or create an
487 @q{anchor} point inside the markup (generally with @code{\hspace
488 #0}).
489
490 @lilypond[quote,verbatim,fragment,relative=1]
491 \textLengthOn
492 c'4^\markup{ \raise #5 "not raised" }
493 \once \override TextScript #'padding = #3
494 c'4^\markup{ raised }
495 c'4^\markup{ \hspace #0 \raise #1.5 raised }
496 @end lilypond
497
498 Some situations (such as dynamic marks) have preset font-related
499 properties.  If you are creating text in such situations, it is
500 advisable to cancel those properties with @code{normal-text}.  See
501 @ref{Overview of text markup commands}, for more details.
502
503
504 @seealso
505
506 This manual: @ref{Overview of text markup commands}.
507
508 Snippets: @lsrdir{Text,Text}
509
510 Internals Reference: @internalsref{TextScript}.
511
512 Init files: @file{scm/@/new@/-markup@/.scm}.
513
514
515 @refbugs
516
517 Kerning or generation of ligatures is only done when the @TeX{}
518 backend is used.  In this case, LilyPond does not account for them
519 so texts will be spaced slightly too wide.
520
521 Syntax errors for markup mode are confusing.
522
523
524 @node Nested scores
525 @subsubsection Nested scores
526
527 It is possible to nest music inside markups, by adding a
528 @code{\score} block to a markup expression.  Such a score must
529 contain a @code{\layout} block.
530
531 @lilypond[quote,verbatim,ragged-right]
532 \relative {
533   c4 d^\markup {
534     \score {
535       \relative { c4 d e f }
536       \layout { }
537     }
538   }
539   e f
540 }
541 @end lilypond
542
543 @seealso
544
545 Snippets: @lsrdir{Text,Text}
546
547 @node Page wrapping text
548 @subsubsection Page wrapping text
549
550 Whereas @code{\markup} is used to enter a non-breakable block of
551 text, @code{\markuplines} can be used at top-level to enter lines
552 of text that can spread over multiple pages:
553
554 @verbatim
555 \markuplines {
556   \justified-lines {
557     A very long text of justified lines.
558     ...
559   }
560   \justified-lines {
561     An other very long paragraph.
562     ...
563   }
564   ...
565 }
566 @end verbatim
567
568 @code{\markuplines} accepts a list of markup, that is either the
569 result of a markup list command, or a list of markups or of markup
570 lists.  The built-in markup list commands are described in
571 @ref{Overview of text markup list commands}.
572
573 @seealso
574
575 This manual: @ref{Overview of text markup list commands}, @ref{New
576 markup list command definition}.
577
578 Snippets: @lsrdir{Text,Text}
579
580 @refcommands
581
582 @funindex \markuplines
583 @code{\markuplines}
584
585 @node Font selection
586 @subsubsection Font selection
587
588 @cindex font selection
589 @cindex font magnification
590 @funindex font-interface
591
592 By setting the object properties described below, you can select a
593 font from the preconfigured font families.  LilyPond has default
594 support for the feta music fonts.  Text fonts are selected through
595 Pango/FontConfig.  The serif font defaults to New Century
596 Schoolbook, the sans and typewriter to whatever the Pango
597 installation defaults to.
598
599
600 @itemize
601 @item @code{font-encoding}
602 is a symbol that sets layout of the glyphs.  This should only be
603 set to select different types of non-text fonts, e.g.
604
605 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
606 standard music font, including ancient glyphs, @code{fetaDynamic}
607 for dynamic signs and @code{fetaNumber} for the number font.
608
609 @item @code{font-family}
610 is a symbol indicating the general class of the typeface.
611 Supported are @code{roman} (Computer Modern), @code{sans}, and
612 @code{typewriter}.
613
614 @item @code{font-shape}
615 is a symbol indicating the shape of the font.  There are typically
616 several font shapes available for each font family.  Choices are
617 @code{italic}, @code{caps}, and @code{upright}.
618
619 @item @code{font-series}
620 is a symbol indicating the series of the font.  There are
621 typically several font series for each font family and shape.
622 Choices are @code{medium} and @code{bold}.
623
624 @end itemize
625
626 Fonts selected in the way sketched above come from a predefined
627 style sheet.  If you want to use a font from outside the style
628 sheet, then set the @code{font-name} property,
629
630 @lilypond[fragment,verbatim]
631 {
632   \override Staff.TimeSignature #'font-name = #"Charter"
633   \override Staff.TimeSignature #'font-size = #2
634   \time 3/4
635   c'1_\markup {
636     \override #'(font-name . "Vera Bold")
637       { This text is in Vera Bold }
638   }
639 }
640 @end lilypond
641
642 @noindent
643 Any font can be used, as long as it is available to
644 Pango/FontConfig.  To get a full list of all available fonts, run
645 the command
646
647 @example
648 lilypond -dshow-available-fonts blabla
649 @end example
650
651 (the last argument of the command can be anything, but has to be
652 present).
653
654
655 The size of the font may be set with the @code{font-size}
656 property.  The resulting size is taken relative to the
657 @code{text-font-size} as defined in the @code{\paper} block.
658
659 @cindex font size
660 @cindex font magnification
661
662
663 It is also possible to change the default font family for the
664 entire document.  This is done by calling the
665 @code{make-pango-font-tree} from within the @code{\paper} block.
666 The function takes names for the font families to use for roman,
667 sans serif and monospaced text.  For example,
668
669 @cindex font families, setting
670 @cindex Pango
671
672
673 @lilypond[verbatim]
674 \paper  {
675   myStaffSize = #20
676
677   #(define fonts
678     (make-pango-font-tree "Times New Roman"
679                           "Nimbus Sans"
680                           "Luxi Mono"
681                            (/ myStaffSize 20)))
682 }
683
684 {
685   c'^\markup { roman: foo \sans bla \typewriter bar }
686 }
687 @end lilypond
688
689 @c we don't do Helvetica / Courier, since GS incorrectly loads
690 @c Apple TTF fonts
691
692
693
694 @seealso
695
696 Snippets: @lsrdir{Text,Text}
697
698
699 @node Special text concerns
700 @subsection Special text concerns
701
702
703
704 @menu
705 * New dynamic marks::           
706 * Text and line spanners::      
707 @end menu
708
709 @node New dynamic marks
710 @subsubsection New dynamic marks
711
712 It is possible to print new dynamic marks or text that should be
713 aligned with dynamics.  Use @code{make-dynamic-script} to create
714 these marks.  Note that the dynamic font only contains the
715 characters @code{f,m,p,r,s} and @code{z}.
716
717 Some situations (such as dynamic marks) have preset font-related
718 properties.  If you are creating text in such situations, it is
719 advisable to cancel those properties with @code{normal-text}.  See
720 @ref{Overview of text markup commands}, for more details.
721
722 @cindex make-dynamic-script
723
724 @lilypond[quote,verbatim,ragged-right]
725 sfzp = #(make-dynamic-script "sfzp")
726 \relative c' {
727   c4 c c\sfzp c
728 }
729 @end lilypond
730
731 @cindex Dynamics, editorial
732 @cindex Dynamics, parenthesis
733
734 It is also possible to print dynamics in round parenthesis or
735 square brackets.  These are often used for adding editorial
736 dynamics.
737
738 @lilypond[quote,verbatim,ragged-right]
739 rndf = \markup{ \center-align {\line { \bold{\italic (}
740   \dynamic f \bold{\italic )} }} }
741 boxf = \markup{ \bracket { \dynamic f } }
742 { c'1_\rndf c'1_\boxf }
743 @end lilypond
744
745 @seealso
746
747 Snippets: @lsrdir{Text,Text}
748
749
750 @node Text and line spanners
751 @subsubsection Text and line spanners
752
753 Some performance indications, e.g., @i{rallentando} and
754 @i{accelerando} and @i{trills} are written as text and are
755 extended over many measures with lines, sometimes dotted or wavy.
756
757 These all use the same routines as the glissando for drawing the
758 texts and the lines, and tuning their behavior is therefore also
759 done in the same way.  It is done with a spanner, and the routine
760 responsible for drawing the spanners is
761 @code{ly:line-interface::print}.  This routine determines the
762 exact location of the two @i{span points} and draws a line in
763 between, in the style requested.
764
765 Here is an example of the different line styles available, and how
766 to tune them.
767
768 @lilypond[relative=2,ragged-right,verbatim,fragment]
769 d2 \glissando d'2
770 \once \override Glissando #'style = #'dashed-line
771 d,2 \glissando d'2
772 \override Glissando #'style = #'dotted-line
773 d,2 \glissando d'2
774 \override Glissando #'style = #'zigzag
775 d,2 \glissando d'2
776 \override Glissando #'style = #'trill
777 d,2 \glissando d'2
778 @end lilypond
779
780 The information that determines the end-points is computed
781 on-the-fly for every graphic object, but it is possible to
782 override these. 
783
784 @lilypond[relative=2,ragged-right,verbatim,fragment]
785 e2 \glissando f
786 \once \override Glissando #'bound-details #'right #'Y = #-2
787 e2 \glissando f
788 @end lilypond
789
790 The @code{Glissando} object, like any other using the
791 @code{ly:line-interface::print} routine, carries a nested
792 association list.  In the above statement, the value for @code{Y}
793 is set to @code{-2} for the association list corresponding to the
794 right end point.  Of course, it is also possible to adjust the
795 left side with @code{left} instead of @code{right}.
796
797 If @code{Y} is not set, the value is computed from the vertical
798 position of right attachment point of the spanner. 
799
800 In case of a line break, the values for the span-points are
801 extended with contents of the @code{left-broken} and
802 @code{right-broken} sublists, for example
803
804 @lilypond[relative=2,ragged-right,verbatim,fragment]
805 \override Glissando #'breakable = ##T 
806 \override Glissando #'bound-details #'right-broken #'Y = #-3
807 c1 \glissando \break
808 f1
809 @end lilypond
810
811 The following properties can be used for the
812
813 @table @code
814 @item Y
815 This sets the Y-coordinate of the end point, in staff space.  By
816 default, it is the center of the bound object, so for a glissando
817 it points to the vertical center of the note head.
818
819 For horizontal spanners, such as text spanner and trill spanners,
820 it is hardcoded to 0.
821
822 @item attach-dir
823 This determines where the line starts and ends in X-direction,
824 relative to the bound object.  So, a value of @code{-1} (or
825 @code{LEFT}) makes the line start/end at the left side of the note
826 head it is attached to.
827
828 @item X
829 This is the absolute coordinate of the end point.  It is usually
830 computed on the fly, and there is little use in overriding it. 
831
832 @item stencil
833 Line spanners may have symbols at the beginning or end, which is
834 contained in this sub-property.  This is for internal use, it is
835 recommended to use @code{text}.
836
837 @item text
838 This is a markup that is evaluated to yield stencil.  It is used
839 to put @i{cresc.} and @i{tr} on horizontal spanners.
840
841 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
842 \override TextSpanner #'bound-details #'left #'text
843    = \markup { \small \bold Slower }
844 c2\startTextSpan b c a\stopTextSpan
845 @end lilypond
846
847 @item stencil-align-dir-y
848 @item stencil-offset
849 Without setting this, the stencil is simply put there at the
850 end-point, as defined by the @code{X} and @code{Y} sub properties.
851 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
852 will move the symbol at the edge relative to the end point of the
853 line
854
855 @lilypond[relative=1,fragment,verbatim]
856 \override TextSpanner #'bound-details
857   #'left #'stencil-align-dir-y = #DOWN
858 \override TextSpanner #'bound-details
859   #'right #'stencil-align-dir-y = #UP
860
861 \override TextSpanner #'bound-details
862   #'left #'text = #"gggg"
863 \override TextSpanner #'bound-details
864   #'right #'text = #"hhhh"
865 c4^\startTextSpan c c c \stopTextSpan
866 @end lilypond
867
868 @item arrow
869 Setting this sub property to @code{#t} produce an arrowhead at the
870 end of the line.
871
872 @item padding
873 This sub property controls the space between the specified
874 end-point of the line and the actual end.  Without padding, a
875 glissando would start and end in the center of each note head.
876
877 @end table
878
879 TODO: add this somewhere
880
881 @verbatim
882 \new Staff {
883   \override TextSpanner #'bound-details #'left-broken #'text = ##f
884    \override TextSpanner #'bound-details #'left #'text = \markup {
885 "start" }
886    c'1 \startTextSpan \break
887    c'1
888    c'1 \stopTextSpan
889 }
890 @end verbatim
891
892
893 The music function \endSpanners terminates spanners and hairpins
894 after exactly one note.
895
896 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
897 \endSpanners
898 c2 \startTextSpan c2
899 c2 \< c2
900 @end lilypond
901
902 When using \endSpanners it is not necessary to close
903 \startTextSpan with \stopTextSpan, nor is it necessary to close
904 hairpins with \!.
905
906
907
908 @seealso
909
910 Snippets: @lsrdir{Text,Text}
911
912 Internals Reference: @internalsref{TextSpanner},
913 @internalsref{Glissando}, @internalsref{VoiceFollower},
914 @internalsref{TrillSpanner},
915 @internalsref{line-spanner-interface}.
916
917
918
919
920