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]{text-headword.ly}
14 This section explains how to include text (with various
15 formatting) in your scores.
17 @cindex Text, other languages
18 @warning{To write accented and special text (such as characters
19 from other languages), simply insert the characters directly into
20 the lilypond file. The file must be saved as UTF-8. For more
21 information, see @ref{Text encoding}.}
26 * Special text concerns::
31 @subsection Writing text
34 * Overview of text entry::
40 @node Overview of text entry
41 @subsubsection Overview of text entry
43 There are four ways to add text to scores:
47 @ref{Text scripts}: blah blah
49 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
54 @ref{Text spanners}: blah blah
56 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
58 \override TextSpanner #'bound-details #'left #'text =
59 \markup { \upright "rall" }
60 c2\startTextSpan b c\stopTextSpan a
64 @ref{Text marks}: blah blah
66 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
71 @ref{Vocal music}: blah blah, not in this section.
73 @lilypond[verbatim,quote,ragged-right]
75 \relative c'' { c4 c c c }
76 \addlyrics { one two three four }
84 Snippets: @lsrdir{Text,Text}
89 @subsubsection Text scripts
92 @cindex text items, non-empty
93 @cindex non-empty texts
95 It is possible to add arbitrary text indications with
96 @var{note}@code{-"}@var{text}@code{"}.
97 Such indications can also be manually placed
98 above or below the staff, using the
99 simple syntax described in @ref{Controlling direction and
102 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
103 d8^"pizz." e f g a4-"scherz." f
106 In LilyPond, such text strings are called @command{markup}
107 objects. This syntax is actually a shorthand; more complex text
108 formatting may be added to a note by explicitly using the
109 @code{\markup} command, as described in @ref{Text markup}.
111 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
112 d8^\markup { \italic pizz. } e f g
113 a4_\markup { \tiny scherz. \bold molto } f
118 @funindex \textLengthOn
119 @code{\textLengthOn},
120 @funindex \textLengthOff
121 @code{\textLengthOff}.
123 By default, text indications do not influence the note spacing.
124 However, their widths can be taken into account using the following
129 @var{note}@code{-"text"}
133 In the following example, the first text string does not affect
134 spacing, whereas the second one does.
136 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
137 d8^"pizz." e f g \textLengthOn a4_"scherzando" f
143 @c FIXME: add an example and LSR-ize this? -vv
144 Checking to make sure that text scripts and lyrics are within the
145 margins is a relatively large computational task. To speed up
146 processing, lilypond does not perform such calculations by
147 default; to enable it, use
150 \override Score.PaperColumn #'keep-inside-line = ##t
156 Notation Reference: @ref{Text markup}.
158 Snippets: @lsrdir{Text,Text}
160 Internals Reference: @internalsref{TextScript}.
164 @subsubsection Text spanners
166 @cindex Text spanners
168 @c TODO: merge these explanations with the ones below in
169 @c "Text and Line spanners" -vv
171 Some performance indications, e.g., @i{rallentando} or
172 @i{accelerando}, are written as text and are extended over many
173 measures with dotted lines. Such texts are created using text
174 spanners; attach @code{\startTextSpan} and @code{\stopTextSpan} to
175 the first and last notes of the spanner.
177 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
179 \override TextSpanner #'bound-details #'left #'text = "faster"
180 c2\startTextSpan b c\stopTextSpan a
184 The string to be printed, as well as the style, is set through
185 object properties. It can accept @code{\markup} blocks as well:
187 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
190 \override TextSpanner #'bound-details #'left #'text =
191 \markup { \upright "rall" }
192 c2\startTextSpan b c\stopTextSpan a
195 \override TextSpanner #'bound-details #'left #'text =
196 \markup { \italic "rit" }
197 c2\startTextSpan b c\stopTextSpan a
202 @funindex textSpannerUp
203 @code{\textSpannerUp},
204 @funindex textSpannerDown
205 @code{\textSpannerDown},
206 @funindex textSpannerNeutral
207 @code{\textSpannerNeutral}.
212 To print a solid line, use
215 \override TextSpanner #'style = #'line
221 Snippets: @lsrdir{Text,Text}
223 Internals Reference: @internalsref{TextSpanner}.
227 @subsubsection Text marks
229 @cindex coda on bar line
230 @cindex segno on bar line
231 @cindex fermata on bar line
232 @cindex bar lines, symbols on
235 The @code{\mark} command is primarily used for @ref{Rehearsal
236 marks}, but it can also be used to add text elements in a score:
238 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
242 As it can contain a @code{\markup} object, the @code{\mark} command
243 makes possible to put any text, but also signs like coda, segno, or
244 fermata on a bar line. The appropriate symbol has to be specified in
245 the @code{\markup} block; these symbols are listed in @ref{The Feta font}.
247 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
248 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
253 @code{\mark} is only typeset above the top staff of the score. If
254 you specify the @code{\mark} command at a bar line, the resulting
255 mark is placed above the bar line. If you specify it in the
256 middle of a bar, the resulting mark is positioned between notes.
257 If it is specified before the beginning of a score line, it is
258 placed before the first note of the line. Finally, if the mark
259 occurs at a line break, the mark will be printed at the beginning
262 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
263 @c delete this sentence. -gp
265 If there is no next line, then the mark will not be printed at
271 @c TODO: to be LSR-ized stuff -vv
273 To print the mark at the end of the current line, use
276 \override Score.RehearsalMark
277 #'break-visibility = #begin-of-line-invisible
280 @code{\mark} is often useful for adding text to the end of bar.
281 In such cases, changing the @code{#'self-alignment} is very useful
283 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
284 \override Score.RehearsalMark
285 #'break-visibility = #begin-of-line-invisible
287 \once \override Score.RehearsalMark #'self-alignment-X = #right
288 \mark "D.S. al Fine "
291 Text marks may be aligned with notation objects other than bar
294 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
299 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
303 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
307 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
316 Possible symbols for the @code{break-align-symbols} list are
317 @code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
318 @code{staff-bar}, @code{left-edge}, @code{key-cancellation},
319 @code{key-signature}, and @code{time-signature}.
321 The text marks will, by default, be aligned with the middle of the
322 notation object, but this can be changed by overriding the
323 @code{break-align-anchor-alignment} and @code{break-align-anchor}
324 properties for the appropriate grob. For scores with multiple staves,
325 this setting should be done for all the staves.
327 @lilypond[fragment,quote,ragged-right,verbatim]
329 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
333 % the RehearsalMark will be aligned with the left edge of the KeySignature
334 \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
339 % the RehearsalMark will be aligned with the right edge of the KeySignature
340 \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
345 % the RehearsalMark will be aligned with the left edge of the KeySignature
346 % and then shifted right by 2 units.
347 \once \override Score.KeySignature #'break-align-anchor = #2
353 Although text marks are normally only printed above the topmost
354 staff, you may alter this to print them on every staff,
356 @lilypond[quote,ragged-right,verbatim,relative=2]
359 \remove "Mark_engraver"
363 \consists "Mark_engraver"
365 { c''1 \mark "foo" c'' }
367 \consists "Mark_engraver"
369 { c'1 \mark "foo" c' }
377 Snippets: @lsrdir{Text,Text}
379 Internals Reference: @internalsref{RehearsalMark}.
381 @c TODO: add this here? -vv
383 @c @subsubsection Text marks
386 @subsection Text markup
389 * Text markup introduction::
391 * Page wrapping text::
395 @node Text markup introduction
396 @subsubsection Text markup introduction
403 Use @code{\markup} to typeset text. Commands are entered with the
404 backslash @code{\}. To enter @code{\} and @code{#}, use double
407 @lilypond[quote,verbatim,fragment,relative=1]
409 c1_\markup { hi there }
410 c1^\markup { hi \bold there, is \italic {anyone home?} }
411 c1_\markup { "\special {weird} #characters" }
415 See @ref{Overview of text markup commands}, for a list of all
418 @code{\markup} is primarily used for @internalsref{TextScript}s,
419 but it can also be used anywhere text is called in lilypond
421 @lilypond[quote,verbatim]
422 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
425 \override Score.RehearsalMark
426 #'break-visibility = #begin-of-line-invisible
427 \override Score.RehearsalMark #'self-alignment-X = #right
429 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
430 c2^\markup{ don't be \flat }
431 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
433 a2\mark \markup{ \large \bold Fine }
437 \addlyrics { bar, foo \markup{ \italic bar! } }
441 A @code{\markup} command can also be placed on its own, away from
442 any @code{\score} block, see @ref{Multiple scores in a book}.
444 @lilypond[quote,ragged-right,verbatim]
445 \markup{ Here is some text. }
448 @cindex font switching
450 The markup in the example demonstrates font switching commands.
451 The command @code{\bold} and @code{\italic} apply to the first
452 following word only; to apply a command to more than one word,
453 enclose the words with braces,
456 \markup @{ \bold @{ hi there @} @}
460 For clarity, you can also do this for single arguments, e.g.,
463 \markup @{ is \italic @{ anyone @} home @}
466 In markup mode you can compose expressions, similar to
467 mathematical expressions, XML documents, and music expressions.
468 You can stack expressions grouped vertically with the command
469 @code{\column}. Similarly, @code{\center-align} aligns texts by
472 @lilypond[quote,verbatim,fragment,relative=1]
473 c1^\markup { \column { a bbbb \line { c d } } }
474 c1^\markup { \center-align { a bbbb c } }
475 c1^\markup { \line { a b c } }
478 Lists with no previous command are not kept distinct. The
482 \center-align @{ @{ a b @} @{ c d @} @}
490 \center-align @{ a b c d @}
495 To keep lists of words distinct, please use quotes @code{"} or
496 the @code{\line} command
498 @lilypond[quote,verbatim,fragment,relative=1]
500 c4^\markup{ \center-align { on three lines } }
501 c4^\markup{ \center-align { "all one line" } }
502 c4^\markup{ \center-align { { on three lines } } }
503 c4^\markup{ \center-align { \line { on one line } } }
506 Markups can be stored in variables and these variables may be
507 attached to notes, like
510 allegro = \markup @{ \bold \large @{ Allegro @} @}
511 @{ a^\allegro b c d @}
514 Some objects have alignment procedures of their own, which cancel
515 out any effects of alignments applied to their markup arguments as
516 a whole. For example, the @internalsref{RehearsalMark} is
517 horizontally centered, so using @code{\mark \markup @{ \left-align
518 .. @}} has no effect.
520 In addition, vertical placement is performed after creating the
521 text markup object. If you wish to move an entire piece of
522 markup, you need to use the #'padding property or create an
523 @q{anchor} point inside the markup (generally with @code{\hspace
526 @lilypond[quote,verbatim,fragment,relative=1]
528 c'4^\markup{ \raise #5 "not raised" }
529 \once \override TextScript #'padding = #3
530 c'4^\markup{ raised }
531 c'4^\markup{ \hspace #0 \raise #1.5 raised }
534 Some situations (such as dynamic marks) have preset font-related
535 properties. If you are creating text in such situations, it is
536 advisable to cancel those properties with @code{normal-text}. See
537 @ref{Overview of text markup commands}, for more details.
542 This manual: @ref{Overview of text markup commands}.
544 Snippets: @lsrdir{Text,Text}
546 Internals Reference: @internalsref{TextScript}.
548 Init files: @file{scm/@/new@/-markup@/.scm}.
553 Kerning or generation of ligatures is only done when the @TeX{}
554 backend is used. In this case, LilyPond does not account for them
555 so texts will be spaced slightly too wide.
557 Syntax errors for markup mode are confusing.
561 @subsubsection Nested scores
563 It is possible to nest music inside markups, by adding a
564 @code{\score} block to a markup expression. Such a score must
565 contain a @code{\layout} block.
567 @lilypond[quote,verbatim,ragged-right]
571 \relative { c4 d e f }
581 Snippets: @lsrdir{Text,Text}
583 @node Page wrapping text
584 @subsubsection Page wrapping text
586 Whereas @code{\markup} is used to enter a non-breakable block of
587 text, @code{\markuplines} can be used at top-level to enter lines
588 of text that can spread over multiple pages:
593 A very long text of justified lines.
597 An other very long paragraph.
604 @code{\markuplines} accepts a list of markup, that is either the
605 result of a markup list command, or a list of markups or of markup
606 lists. The built-in markup list commands are described in
607 @ref{Overview of text markup list commands}.
611 This manual: @ref{Overview of text markup list commands}, @ref{New
612 markup list command definition}.
614 Snippets: @lsrdir{Text,Text}
618 @funindex \markuplines
622 @subsubsection Font selection
624 @cindex font selection
625 @cindex font magnification
626 @funindex font-interface
628 By setting the object properties described below, you can select a
629 font from the preconfigured font families. LilyPond has default
630 support for the feta music fonts. Text fonts are selected through
631 Pango/FontConfig. The serif font defaults to New Century
632 Schoolbook, the sans and typewriter to whatever the Pango
633 installation defaults to.
637 @item @code{font-encoding}
638 is a symbol that sets layout of the glyphs. This should only be
639 set to select different types of non-text fonts, e.g.
641 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
642 standard music font, including ancient glyphs, @code{fetaDynamic}
643 for dynamic signs and @code{fetaNumber} for the number font.
645 @item @code{font-family}
646 is a symbol indicating the general class of the typeface.
647 Supported are @code{roman} (Computer Modern), @code{sans}, and
650 @item @code{font-shape}
651 is a symbol indicating the shape of the font. There are typically
652 several font shapes available for each font family. Choices are
653 @code{italic}, @code{caps}, and @code{upright}.
655 @item @code{font-series}
656 is a symbol indicating the series of the font. There are
657 typically several font series for each font family and shape.
658 Choices are @code{medium} and @code{bold}.
662 Fonts selected in the way sketched above come from a predefined
663 style sheet. If you want to use a font from outside the style
664 sheet, then set the @code{font-name} property,
666 @lilypond[fragment,verbatim]
668 \override Staff.TimeSignature #'font-name = #"Charter"
669 \override Staff.TimeSignature #'font-size = #2
672 \override #'(font-name . "Vera Bold")
673 { This text is in Vera Bold }
679 Any font can be used, as long as it is available to
680 Pango/FontConfig. To get a full list of all available fonts, run
684 lilypond -dshow-available-fonts blabla
687 (the last argument of the command can be anything, but has to be
691 The size of the font may be set with the @code{font-size}
692 property. The resulting size is taken relative to the
693 @code{text-font-size} as defined in the @code{\paper} block.
696 @cindex font magnification
699 It is also possible to change the default font family for the
700 entire document. This is done by calling the
701 @code{make-pango-font-tree} from within the @code{\paper} block.
702 The function takes names for the font families to use for roman,
703 sans serif and monospaced text. For example,
705 @cindex font families, setting
714 (make-pango-font-tree "Times New Roman"
721 c'^\markup { roman: foo \sans bla \typewriter bar }
725 @c we don't do Helvetica / Courier, since GS incorrectly loads
732 Snippets: @lsrdir{Text,Text}
735 @node Special text concerns
736 @subsection Special text concerns
738 @c FIXME: this section is to be removed
739 @c (see comments below) -vv
742 * New dynamic marks::
743 * Text and line spanners::
746 @node New dynamic marks
747 @subsubsection New dynamic marks
749 @c FIXME: this whole section should be removed and put in
750 @c "Writing text" -vv
752 It is possible to print new dynamic marks or text that should be
753 aligned with dynamics. Use @code{make-dynamic-script} to create
754 these marks. Note that the dynamic font only contains the
755 characters @code{f,m,p,r,s} and @code{z}.
757 Some situations (such as dynamic marks) have preset font-related
758 properties. If you are creating text in such situations, it is
759 advisable to cancel those properties with @code{normal-text}. See
760 @ref{Overview of text markup commands}, for more details.
762 @cindex make-dynamic-script
764 @lilypond[quote,verbatim,ragged-right]
765 sfzp = #(make-dynamic-script "sfzp")
771 @cindex Dynamics, editorial
772 @cindex Dynamics, parenthesis
774 It is also possible to print dynamics in round parenthesis or
775 square brackets. These are often used for adding editorial
778 @lilypond[quote,verbatim,ragged-right]
779 rndf = \markup{ \center-align {\line { \bold{\italic (}
780 \dynamic f \bold{\italic )} }} }
781 boxf = \markup{ \bracket { \dynamic f } }
782 { c'1_\rndf c'1_\boxf }
787 Snippets: @lsrdir{Text,Text}
790 @node Text and line spanners
791 @subsubsection Text and line spanners
793 @c FIXME: this whole section has to be removed.
794 @c glissando stuff should go into Expressive marks;
795 @c Text spanners should go into... Text spanners.
798 Some performance indications, e.g., @i{rallentando} and
799 @i{accelerando} and @i{trills} are written as text and are
800 extended over many measures with lines, sometimes dotted or wavy.
802 These all use the same routines as the glissando for drawing the
803 texts and the lines, and tuning their behavior is therefore also
804 done in the same way. It is done with a spanner, and the routine
805 responsible for drawing the spanners is
806 @code{ly:line-interface::print}. This routine determines the
807 exact location of the two @i{span points} and draws a line in
808 between, in the style requested.
810 Here is an example of the different line styles available, and how
813 @lilypond[relative=2,ragged-right,verbatim,fragment]
815 \once \override Glissando #'style = #'dashed-line
817 \override Glissando #'style = #'dotted-line
819 \override Glissando #'style = #'zigzag
821 \override Glissando #'style = #'trill
825 The information that determines the end-points is computed
826 on-the-fly for every graphic object, but it is possible to
829 @lilypond[relative=2,ragged-right,verbatim,fragment]
831 \once \override Glissando #'bound-details #'right #'Y = #-2
835 The @code{Glissando} object, like any other using the
836 @code{ly:line-interface::print} routine, carries a nested
837 association list. In the above statement, the value for @code{Y}
838 is set to @code{-2} for the association list corresponding to the
839 right end point. Of course, it is also possible to adjust the
840 left side with @code{left} instead of @code{right}.
842 If @code{Y} is not set, the value is computed from the vertical
843 position of right attachment point of the spanner.
845 In case of a line break, the values for the span-points are
846 extended with contents of the @code{left-broken} and
847 @code{right-broken} sublists, for example
849 @lilypond[relative=2,ragged-right,verbatim,fragment]
850 \override Glissando #'breakable = ##T
851 \override Glissando #'bound-details #'right-broken #'Y = #-3
856 The following properties can be used for the
860 This sets the Y-coordinate of the end point, in staff space. By
861 default, it is the center of the bound object, so for a glissando
862 it points to the vertical center of the note head.
864 For horizontal spanners, such as text spanner and trill spanners,
865 it is hardcoded to 0.
868 This determines where the line starts and ends in X-direction,
869 relative to the bound object. So, a value of @code{-1} (or
870 @code{LEFT}) makes the line start/end at the left side of the note
871 head it is attached to.
874 This is the absolute coordinate of the end point. It is usually
875 computed on the fly, and there is little use in overriding it.
878 Line spanners may have symbols at the beginning or end, which is
879 contained in this sub-property. This is for internal use, it is
880 recommended to use @code{text}.
883 This is a markup that is evaluated to yield stencil. It is used
884 to put @i{cresc.} and @i{tr} on horizontal spanners.
886 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
887 \override TextSpanner #'bound-details #'left #'text
888 = \markup { \small \bold Slower }
889 c2\startTextSpan b c a\stopTextSpan
892 @item stencil-align-dir-y
894 Without setting this, the stencil is simply put there at the
895 end-point, as defined by the @code{X} and @code{Y} sub properties.
896 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
897 will move the symbol at the edge relative to the end point of the
900 @lilypond[relative=1,fragment,verbatim]
901 \override TextSpanner #'bound-details
902 #'left #'stencil-align-dir-y = #DOWN
903 \override TextSpanner #'bound-details
904 #'right #'stencil-align-dir-y = #UP
906 \override TextSpanner #'bound-details
907 #'left #'text = #"gggg"
908 \override TextSpanner #'bound-details
909 #'right #'text = #"hhhh"
910 c4^\startTextSpan c c c \stopTextSpan
914 Setting this sub property to @code{#t} produce an arrowhead at the
918 This sub property controls the space between the specified
919 end-point of the line and the actual end. Without padding, a
920 glissando would start and end in the center of each note head.
924 TODO: add this somewhere
928 \override TextSpanner #'bound-details #'left-broken #'text = ##f
929 \override TextSpanner #'bound-details #'left #'text = \markup {
931 c'1 \startTextSpan \break
938 The music function \endSpanners terminates spanners and hairpins
939 after exactly one note.
941 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
947 When using \endSpanners it is not necessary to close
948 \startTextSpan with \stopTextSpan, nor is it necessary to close
955 Snippets: @lsrdir{Text,Text}
957 Internals Reference: @internalsref{TextSpanner},
958 @internalsref{Glissando}, @internalsref{VoiceFollower},
959 @internalsref{TrillSpanner},
960 @internalsref{line-spanner-interface}.