1 @c -*- coding: utf-8; mode: texinfo; -*-
3 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5 When revising a translation, copy the HEAD committish of the
6 version that you are working on. See TRANSLATION for details.
12 @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
15 This section explains how to include text (with various
16 formatting) in your scores.
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}.
27 * Special text concerns::
32 @subsection Writing text
35 * Overview of text entry::
41 @node Overview of text entry
42 @unnumberedsubsubsec Overview of text entry
44 There are four ways to add text to scores:
48 @ref{Text scripts}: blah blah
50 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
55 @ref{Text spanners}: blah blah
57 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
59 \override TextSpanner #'bound-details #'left #'text =
60 \markup { \upright "rall" }
61 c2\startTextSpan b c\stopTextSpan a
65 @ref{Text marks}: blah blah
67 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
72 @ref{Vocal music}: blah blah, not in this section.
74 @lilypond[verbatim,quote,ragged-right]
76 \relative c'' { c4 c c c }
77 \addlyrics { one two three four }
85 Snippets: @lsrdir{text}
90 @unnumberedsubsubsec Text scripts
93 @cindex text items, non-empty
94 @cindex non-empty texts
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
102 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
103 c4^"longtext" \textLengthOn c4_"longlongtext" c4
107 To prevent text from influencing spacing, use @code{\textLengthOff}.
109 More complex formatting may also be added to a note by using the
112 @lilypond[fragment,ragged-right,verbatim,quote]
113 c'4^\markup { bla \bold bla }
116 The @code{\markup} is described in more detail in @ref{Text
122 @funindex \textLengthOn
123 @code{\textLengthOn},
124 @funindex \textLengthOff
125 @code{\textLengthOff}.
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
136 \override Score.PaperColumn #'keep-inside-line = ##t
142 Notation Reference: @ref{Text markup}.
144 Snippets: @lsrdir{text}
146 Internals Reference: @internalsref{TextScript}.
150 @unnumberedsubsubsec Text spanners
152 @cindex Text spanners
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.
160 The string to be printed, as well as the style, is set through
163 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
166 \override TextSpanner #'bound-details #'left #'text =
167 \markup { \upright "rall" }
168 c2\startTextSpan b c\stopTextSpan a
171 \override TextSpanner #'bound-details #'left #'text =
172 \markup { \italic "rit" }
173 c2\startTextSpan b c\stopTextSpan a
178 @funindex textSpannerUp
179 @code{\textSpannerUp},
180 @funindex textSpannerDown
181 @code{\textSpannerDown},
182 @funindex textSpannerNeutral
183 @code{\textSpannerNeutral}.
188 To print a solid line, use
191 \override TextSpanner #'style = #'line
197 Snippets: @lsrdir{text}
199 Internals Reference: @internalsref{TextSpanner}.
203 @unnumberedsubsubsec Text marks
205 @cindex coda on bar line
206 @cindex segno on bar line
207 @cindex fermata on bar line
208 @cindex bar lines, symbols on
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}).
216 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
217 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
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
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
239 To print the mark at the end of the current line, use
242 \override Score.RehearsalMark
243 #'break-visibility = #begin-of-line-invisible
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
249 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
250 \override Score.RehearsalMark
251 #'break-visibility = #begin-of-line-invisible
253 \once \override Score.RehearsalMark #'self-alignment-X = #right
254 \mark "D.S. al Fine "
257 Text marks may be aligned with notation objects other than bar
260 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
265 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
269 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
273 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
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}.
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.
292 @lilypond[fragment,quote,ragged-right,verbatim]
294 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
298 % the RehearsalMark will be aligned with the left edge of the KeySignature
299 \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT
304 % the RehearsalMark will be aligned with the right edge of the KeySignature
305 \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT
310 % the RehearsalMark will be aligned with the left edge of the KeySignature
311 % and then shifted right by 2 units.
312 \once \override Staff.KeySignature #'break-align-anchor = #2
318 Although text marks are normally only printed above the topmost
319 staff, you may alter this to print them on every staff,
321 @lilypond[quote,ragged-right,verbatim,relative=2]
324 \remove "Mark_engraver"
328 \consists "Mark_engraver"
330 { c''1 \mark "foo" c'' }
332 \consists "Mark_engraver"
334 { c'1 \mark "foo" c' }
342 Snippets: @lsrdir{text}
344 Internals Reference: @internalsref{RehearsalMark}.
349 @subsection Text markup
352 * Text markup introduction::
354 * Page wrapping text::
358 @node Text markup introduction
359 @unnumberedsubsubsec Text markup introduction
366 Use @code{\markup} to typeset text. Commands are entered with the
367 backslash @code{\}. To enter @code{\} and @code{#}, use double
370 @lilypond[quote,verbatim,fragment,relative=1]
372 c1_\markup { hi there }
373 c1^\markup { hi \bold there, is \italic {anyone home?} }
374 c1_\markup { "\special {weird} #characters" }
378 See @ref{Overview of text markup commands}, for a list of all
381 @code{\markup} is primarily used for @internalsref{TextScript}s,
382 but it can also be used anywhere text is called in lilypond
384 @lilypond[quote,verbatim]
385 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
388 \override Score.RehearsalMark
389 #'break-visibility = #begin-of-line-invisible
390 \override Score.RehearsalMark #'self-alignment-X = #right
392 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
393 c2^\markup{ don't be \flat }
394 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
396 a2\mark \markup{ \large \bold Fine }
400 \addlyrics { bar, foo \markup{ \italic bar! } }
404 A @code{\markup} command can also be placed on its own, away from
405 any @code{\score} block, see @ref{Multiple scores in a book}.
407 @lilypond[quote,ragged-right,verbatim]
408 \markup{ Here is some text. }
411 @cindex font switching
413 The markup in the example demonstrates font switching commands.
414 The command @code{\bold} and @code{\italic} apply to the first
415 following word only; to apply a command to more than one word,
416 enclose the words with braces,
419 \markup @{ \bold @{ hi there @} @}
423 For clarity, you can also do this for single arguments, e.g.,
426 \markup @{ is \italic @{ anyone @} home @}
429 In markup mode you can compose expressions, similar to
430 mathematical expressions, XML documents, and music expressions.
431 You can stack expressions grouped vertically with the command
432 @code{\column}. Similarly, @code{\center-align} aligns texts by
435 @lilypond[quote,verbatim,fragment,relative=1]
436 c1^\markup { \column { a bbbb \line { c d } } }
437 c1^\markup { \center-align { a bbbb c } }
438 c1^\markup { \line { a b c } }
441 Lists with no previous command are not kept distinct. The
445 \center-align @{ @{ a b @} @{ c d @} @}
453 \center-align @{ a b c d @}
458 To keep lists of words distinct, please use quotes @code{"} or
459 the @code{\line} command
461 @lilypond[quote,verbatim,fragment,relative=1]
463 c4^\markup{ \center-align { on three lines } }
464 c4^\markup{ \center-align { "all one line" } }
465 c4^\markup{ \center-align { { on three lines } } }
466 c4^\markup{ \center-align { \line { on one line } } }
469 Markups can be stored in variables and these variables may be
470 attached to notes, like
473 allegro = \markup @{ \bold \large @{ Allegro @} @}
474 @{ a^\allegro b c d @}
477 Some objects have alignment procedures of their own, which cancel
478 out any effects of alignments applied to their markup arguments as
479 a whole. For example, the @internalsref{RehearsalMark} is
480 horizontally centered, so using @code{\mark \markup @{ \left-align
481 .. @}} has no effect.
483 In addition, vertical placement is performed after creating the
484 text markup object. If you wish to move an entire piece of
485 markup, you need to use the #'padding property or create an
486 @q{anchor} point inside the markup (generally with @code{\hspace
489 @lilypond[quote,verbatim,fragment,relative=1]
491 c'4^\markup{ \raise #5 "not raised" }
492 \once \override TextScript #'padding = #3
493 c'4^\markup{ raised }
494 c'4^\markup{ \hspace #0 \raise #1.5 raised }
497 Some situations (such as dynamic marks) have preset font-related
498 properties. If you are creating text in such situations, it is
499 advisable to cancel those properties with @code{normal-text}. See
500 @ref{Overview of text markup commands}, for more details.
505 This manual: @ref{Overview of text markup commands}.
507 Snippets: @lsrdir{text}
509 Internals Reference: @internalsref{TextScript}.
511 Init files: @file{scm/@/new@/-markup@/.scm}.
516 Kerning or generation of ligatures is only done when the @TeX{}
517 backend is used. In this case, LilyPond does not account for them
518 so texts will be spaced slightly too wide.
520 Syntax errors for markup mode are confusing.
524 @unnumberedsubsubsec Nested scores
526 It is possible to nest music inside markups, by adding a
527 @code{\score} block to a markup expression. Such a score must
528 contain a @code{\layout} block.
530 @lilypond[quote,verbatim,ragged-right]
534 \relative { c4 d e f }
544 Snippets: @lsrdir{text}
546 @node Page wrapping text
547 @unnumberedsubsubsec Page wrapping text
549 Whereas @code{\markup} is used to enter a non-breakable block of
550 text, @code{\markuplines} can be used at top-level to enter lines
551 of text that can spread over multiple pages:
556 A very long text of justified lines.
560 An other very long paragraph.
567 @code{\markuplines} accepts a list of markup, that is either the
568 result of a markup list command, or a list of markups or of markup
569 lists. The built-in markup list commands are described in
570 @ref{Overview of text markup list commands}.
574 This manual: @ref{Overview of text markup list commands}, @ref{New
575 markup list command definition}.
577 Snippets: @lsrdir{text}
581 @funindex \markuplines
585 @unnumberedsubsubsec Font selection
587 @cindex font selection
588 @cindex font magnification
589 @funindex font-interface
591 By setting the object properties described below, you can select a
592 font from the preconfigured font families. LilyPond has default
593 support for the feta music fonts. Text fonts are selected through
594 Pango/FontConfig. The serif font defaults to New Century
595 Schoolbook, the sans and typewriter to whatever the Pango
596 installation defaults to.
600 @item @code{font-encoding}
601 is a symbol that sets layout of the glyphs. This should only be
602 set to select different types of non-text fonts, e.g.
604 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
605 standard music font, including ancient glyphs, @code{fetaDynamic}
606 for dynamic signs and @code{fetaNumber} for the number font.
608 @item @code{font-family}
609 is a symbol indicating the general class of the typeface.
610 Supported are @code{roman} (Computer Modern), @code{sans}, and
613 @item @code{font-shape}
614 is a symbol indicating the shape of the font. There are typically
615 several font shapes available for each font family. Choices are
616 @code{italic}, @code{caps}, and @code{upright}.
618 @item @code{font-series}
619 is a symbol indicating the series of the font. There are
620 typically several font series for each font family and shape.
621 Choices are @code{medium} and @code{bold}.
625 Fonts selected in the way sketched above come from a predefined
626 style sheet. If you want to use a font from outside the style
627 sheet, then set the @code{font-name} property,
629 @lilypond[fragment,verbatim]
631 \override Staff.TimeSignature #'font-name = #"Charter"
632 \override Staff.TimeSignature #'font-size = #2
635 \override #'(font-name . "Vera Bold")
636 { This text is in Vera Bold }
642 Any font can be used, as long as it is available to
643 Pango/FontConfig. To get a full list of all available fonts, run
647 lilypond -dshow-available-fonts blabla
650 (the last argument of the command can be anything, but has to be
654 The size of the font may be set with the @code{font-size}
655 property. The resulting size is taken relative to the
656 @code{text-font-size} as defined in the @code{\paper} block.
659 @cindex font magnification
662 It is also possible to change the default font family for the
663 entire document. This is done by calling the
664 @code{make-pango-font-tree} from within the @code{\paper} block.
665 The function takes names for the font families to use for roman,
666 sans serif and monospaced text. For example,
668 @cindex font families, setting
677 (make-pango-font-tree "Times New Roman"
684 c'^\markup { roman: foo \sans bla \typewriter bar }
688 @c we don't do Helvetica / Courier, since GS incorrectly loads
695 Snippets: @lsrdir{text}
698 @node Special text concerns
699 @subsection Special text concerns
704 * New dynamic marks::
705 * Text and line spanners::
708 @node New dynamic marks
709 @unnumberedsubsubsec New dynamic marks
711 It is possible to print new dynamic marks or text that should be
712 aligned with dynamics. Use @code{make-dynamic-script} to create
713 these marks. Note that the dynamic font only contains the
714 characters @code{f,m,p,r,s} and @code{z}.
716 Some situations (such as dynamic marks) have preset font-related
717 properties. If you are creating text in such situations, it is
718 advisable to cancel those properties with @code{normal-text}. See
719 @ref{Overview of text markup commands}, for more details.
721 @cindex make-dynamic-script
723 @lilypond[quote,verbatim,ragged-right]
724 sfzp = #(make-dynamic-script "sfzp")
730 @cindex Dynamics, editorial
731 @cindex Dynamics, parenthesis
733 It is also possible to print dynamics in round parenthesis or
734 square brackets. These are often used for adding editorial
737 @lilypond[quote,verbatim,ragged-right]
738 rndf = \markup{ \center-align {\line { \bold{\italic (}
739 \dynamic f \bold{\italic )} }} }
740 boxf = \markup{ \bracket { \dynamic f } }
741 { c'1_\rndf c'1_\boxf }
746 Snippets: @lsrdir{text}
749 @node Text and line spanners
750 @unnumberedsubsubsec Text and line spanners
752 Some performance indications, e.g., @i{rallentando} and
753 @i{accelerando} and @i{trills} are written as text and are
754 extended over many measures with lines, sometimes dotted or wavy.
756 These all use the same routines as the glissando for drawing the
757 texts and the lines, and tuning their behavior is therefore also
758 done in the same way. It is done with a spanner, and the routine
759 responsible for drawing the spanners is
760 @code{ly:line-interface::print}. This routine determines the
761 exact location of the two @i{span points} and draws a line in
762 between, in the style requested.
764 Here is an example of the different line styles available, and how
767 @lilypond[relative=2,ragged-right,verbatim,fragment]
769 \once \override Glissando #'style = #'dashed-line
771 \override Glissando #'style = #'dotted-line
773 \override Glissando #'style = #'zigzag
775 \override Glissando #'style = #'trill
779 The information that determines the end-points is computed
780 on-the-fly for every graphic object, but it is possible to
783 @lilypond[relative=2,ragged-right,verbatim,fragment]
785 \once \override Glissando #'bound-details #'right #'Y = #-2
789 The @code{Glissando} object, like any other using the
790 @code{ly:line-interface::print} routine, carries a nested
791 association list. In the above statement, the value for @code{Y}
792 is set to @code{-2} for the association list corresponding to the
793 right end point. Of course, it is also possible to adjust the
794 left side with @code{left} instead of @code{right}.
796 If @code{Y} is not set, the value is computed from the vertical
797 position of right attachment point of the spanner.
799 In case of a line break, the values for the span-points are
800 extended with contents of the @code{left-broken} and
801 @code{right-broken} sublists, for example
803 @lilypond[relative=2,ragged-right,verbatim,fragment]
804 \override Glissando #'breakable = ##T
805 \override Glissando #'bound-details #'right-broken #'Y = #-3
810 The following properties can be used for the
814 This sets the Y-coordinate of the end point, in staff space. By
815 default, it is the center of the bound object, so for a glissando
816 it points to the vertical center of the note head.
818 For horizontal spanners, such as text spanner and trill spanners,
819 it is hardcoded to 0.
822 This determines where the line starts and ends in X-direction,
823 relative to the bound object. So, a value of @code{-1} (or
824 @code{LEFT}) makes the line start/end at the left side of the note
825 head it is attached to.
828 This is the absolute coordinate of the end point. It is usually
829 computed on the fly, and there is little use in overriding it.
832 Line spanners may have symbols at the beginning or end, which is
833 contained in this sub-property. This is for internal use, it is
834 recommended to use @code{text}.
837 This is a markup that is evaluated to yield stencil. It is used
838 to put @i{cresc.} and @i{tr} on horizontal spanners.
840 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
841 \override TextSpanner #'bound-details #'left #'text
842 = \markup { \small \bold Slower }
843 c2\startTextSpan b c a\stopTextSpan
846 @item stencil-align-dir-y
848 Without setting this, the stencil is simply put there at the
849 end-point, as defined by the @code{X} and @code{Y} sub properties.
850 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
851 will move the symbol at the edge relative to the end point of the
854 @lilypond[relative=1,fragment,verbatim]
855 \override TextSpanner #'bound-details
856 #'left #'stencil-align-dir-y = #DOWN
857 \override TextSpanner #'bound-details
858 #'right #'stencil-align-dir-y = #UP
860 \override TextSpanner #'bound-details
861 #'left #'text = #"gggg"
862 \override TextSpanner #'bound-details
863 #'right #'text = #"hhhh"
864 c4^\startTextSpan c c c \stopTextSpan
868 Setting this sub property to @code{#t} produce an arrowhead at the
872 This sub property controls the space between the specified
873 end-point of the line and the actual end. Without padding, a
874 glissando would start and end in the center of each note head.
878 TODO: add this somewhere
882 \override TextSpanner #'bound-details #'left-broken #'text = ##f
883 \override TextSpanner #'bound-details #'left #'text = \markup {
885 c'1 \startTextSpan \break
892 The music function \endSpanners terminates spanners and hairpins
893 after exactly one note.
895 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
901 When using \endSpanners it is not necessary to close
902 \startTextSpan with \stopTextSpan, nor is it necessary to close
909 Snippets: @lsrdir{text}
911 Internals Reference: @internalsref{TextSpanner},
912 @internalsref{Glissando}, @internalsref{VoiceFollower},
913 @internalsref{TrillSpanner},
914 @internalsref{line-spanner-interface}.