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
116 By default, text indications do not influence the note spacing.
117 However, their widths can be taken into account:
118 in the following example, the first text string does not affect
119 spacing, whereas the second one does.
121 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
122 d8^"pizz." e f g \textLengthOn a4_"scherzando" f
127 @funindex \textLengthOn
128 @code{\textLengthOn},
129 @funindex \textLengthOff
130 @code{\textLengthOff}.
135 Notation Reference: @ref{Text markup}.
137 Snippets: @lsrdir{Text,Text}
139 Internals Reference: @internalsref{TextScript}.
143 Checking to make sure that text scripts and lyrics are within the
144 margins is a relatively large computational task. To speed up
145 processing, lilypond does not perform such calculations by
146 default; to enable it, use
149 \override Score.PaperColumn #'keep-inside-line = ##t
154 @subsubsection Text spanners
156 @cindex Text spanners
158 @c TODO: merge these explanations with the ones below in
159 @c "Text and Line spanners" -vv
161 Some performance indications, e.g., @i{rallentando} or
162 @i{accelerando}, are written as text and are extended over many
163 measures with dotted lines; you can create such text spanners
164 from one note to another by using the following syntax:
166 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
167 \override TextSpanner #'bound-details #'left #'text = "rit."
173 The string to be printed is set through
174 object properties. By default, it is printed in italic characters;
175 however, different formatting can be obtained using
176 @code{\markup} blocks:
178 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
179 \override TextSpanner #'bound-details #'left #'text =
180 \markup { \upright "rit." }
187 @funindex textSpannerUp
188 @code{\textSpannerUp},
189 @funindex textSpannerDown
190 @code{\textSpannerDown},
191 @funindex textSpannerNeutral
192 @code{\textSpannerNeutral}.
194 @c TODO: Document Line Styles? -vv
196 The line style, as well as the text string, can be defined as an
197 object property, as described in @ref{Line Styles}.
203 To print a solid line, use
206 \override TextSpanner #'style = #'line
212 Snippets: @lsrdir{Text,Text}
214 Internals Reference: @internalsref{TextSpanner}.
218 @subsubsection Text marks
220 @cindex coda on bar line
221 @cindex segno on bar line
222 @cindex fermata on bar line
223 @cindex bar lines, symbols on
226 The @code{\mark} command is primarily used for @ref{Rehearsal
227 marks}, but it can also be used to add text elements in a score:
229 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
233 As it can contain a @code{\markup} object, the @code{\mark} command
234 makes possible to put any text, but also signs like coda, segno, or
235 fermata on a bar line. The appropriate symbol has to be specified in
236 the @code{\markup} block; these symbols are listed in @ref{The Feta font}.
238 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
239 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
244 @code{\mark} is only typeset above the top staff of the score. If
245 you specify the @code{\mark} command at a bar line, the resulting
246 mark is placed above the bar line. If you specify it in the
247 middle of a bar, the resulting mark is positioned between notes.
248 If it is specified before the beginning of a score line, it is
249 placed before the first note of the line. Finally, if the mark
250 occurs at a line break, the mark will be printed at the beginning
253 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
254 @c delete this sentence. -gp
256 If there is no next line, then the mark will not be printed at
262 @c TODO: to be LSR-ized stuff -vv
264 To print the mark at the end of the current line, use
267 \override Score.RehearsalMark
268 #'break-visibility = #begin-of-line-invisible
271 @code{\mark} is often useful for adding text to the end of bar.
272 In such cases, changing the @code{#'self-alignment} is very useful
274 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
275 \override Score.RehearsalMark
276 #'break-visibility = #begin-of-line-invisible
278 \once \override Score.RehearsalMark #'self-alignment-X = #right
279 \mark "D.S. al Fine "
282 Text marks may be aligned with notation objects other than bar
285 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
290 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
294 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
298 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
307 Possible symbols for the @code{break-align-symbols} list are
308 @code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
309 @code{staff-bar}, @code{left-edge}, @code{key-cancellation},
310 @code{key-signature}, and @code{time-signature}.
312 The text marks will, by default, be aligned with the middle of the
313 notation object, but this can be changed by overriding the
314 @code{break-align-anchor-alignment} and @code{break-align-anchor}
315 properties for the appropriate grob. For scores with multiple staves,
316 this setting should be done for all the staves.
318 @lilypond[fragment,quote,ragged-right,verbatim]
320 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
324 % the RehearsalMark will be aligned with the left edge of the KeySignature
325 \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
330 % the RehearsalMark will be aligned with the right edge of the KeySignature
331 \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
336 % the RehearsalMark will be aligned with the left edge of the KeySignature
337 % and then shifted right by 2 units.
338 \once \override Score.KeySignature #'break-align-anchor = #2
344 Although text marks are normally only printed above the topmost
345 staff, you may alter this to print them on every staff,
347 @lilypond[quote,ragged-right,verbatim,relative=2]
350 \remove "Mark_engraver"
354 \consists "Mark_engraver"
356 { c''1 \mark "foo" c'' }
358 \consists "Mark_engraver"
360 { c'1 \mark "foo" c' }
368 Snippets: @lsrdir{Text,Text}
370 Internals Reference: @internalsref{RehearsalMark}.
372 @c TODO: add this here? -vv
374 @c @subsubsection Text marks
377 @subsection Text markup
380 * Text markup introduction::
382 * Page wrapping text::
386 @node Text markup introduction
387 @subsubsection Text markup introduction
394 Use @code{\markup} to typeset text. Commands are entered with the
395 backslash @code{\}. To enter @code{\} and @code{#}, use double
398 @lilypond[quote,verbatim,fragment,relative=1]
400 c1_\markup { hi there }
401 c1^\markup { hi \bold there, is \italic {anyone home?} }
402 c1_\markup { "\special {weird} #characters" }
406 See @ref{Overview of text markup commands}, for a list of all
409 @code{\markup} is primarily used for @internalsref{TextScript}s,
410 but it can also be used anywhere text is called in lilypond
412 @lilypond[quote,verbatim]
413 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
416 \override Score.RehearsalMark
417 #'break-visibility = #begin-of-line-invisible
418 \override Score.RehearsalMark #'self-alignment-X = #right
420 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
421 c2^\markup{ don't be \flat }
422 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
424 a2\mark \markup{ \large \bold Fine }
428 \addlyrics { bar, foo \markup{ \italic bar! } }
432 A @code{\markup} command can also be placed on its own, away from
433 any @code{\score} block, see @ref{Multiple scores in a book}.
435 @lilypond[quote,ragged-right,verbatim]
436 \markup{ Here is some text. }
439 @cindex font switching
441 The markup in the example demonstrates font switching commands.
442 The command @code{\bold} and @code{\italic} apply to the first
443 following word only; to apply a command to more than one word,
444 enclose the words with braces,
447 \markup @{ \bold @{ hi there @} @}
451 For clarity, you can also do this for single arguments, e.g.,
454 \markup @{ is \italic @{ anyone @} home @}
457 In markup mode you can compose expressions, similar to
458 mathematical expressions, XML documents, and music expressions.
459 You can stack expressions grouped vertically with the command
460 @code{\column}. Similarly, @code{\center-align} aligns texts by
463 @lilypond[quote,verbatim,fragment,relative=1]
464 c1^\markup { \column { a bbbb \line { c d } } }
465 c1^\markup { \center-align { a bbbb c } }
466 c1^\markup { \line { a b c } }
469 Lists with no previous command are not kept distinct. The
473 \center-align @{ @{ a b @} @{ c d @} @}
481 \center-align @{ a b c d @}
486 To keep lists of words distinct, please use quotes @code{"} or
487 the @code{\line} command
489 @lilypond[quote,verbatim,fragment,relative=1]
491 c4^\markup{ \center-align { on three lines } }
492 c4^\markup{ \center-align { "all one line" } }
493 c4^\markup{ \center-align { { on three lines } } }
494 c4^\markup{ \center-align { \line { on one line } } }
497 Markups can be stored in variables and these variables may be
498 attached to notes, like
501 allegro = \markup @{ \bold \large @{ Allegro @} @}
502 @{ a^\allegro b c d @}
505 Some objects have alignment procedures of their own, which cancel
506 out any effects of alignments applied to their markup arguments as
507 a whole. For example, the @internalsref{RehearsalMark} is
508 horizontally centered, so using @code{\mark \markup @{ \left-align
509 .. @}} has no effect.
511 In addition, vertical placement is performed after creating the
512 text markup object. If you wish to move an entire piece of
513 markup, you need to use the #'padding property or create an
514 @q{anchor} point inside the markup (generally with @code{\hspace
517 @lilypond[quote,verbatim,fragment,relative=1]
519 c'4^\markup{ \raise #5 "not raised" }
520 \once \override TextScript #'padding = #3
521 c'4^\markup{ raised }
522 c'4^\markup{ \hspace #0 \raise #1.5 raised }
525 Some situations (such as dynamic marks) have preset font-related
526 properties. If you are creating text in such situations, it is
527 advisable to cancel those properties with @code{normal-text}. See
528 @ref{Overview of text markup commands}, for more details.
533 This manual: @ref{Overview of text markup commands}.
535 Snippets: @lsrdir{Text,Text}
537 Internals Reference: @internalsref{TextScript}.
539 Init files: @file{scm/@/new@/-markup@/.scm}.
544 Kerning or generation of ligatures is only done when the @TeX{}
545 backend is used. In this case, LilyPond does not account for them
546 so texts will be spaced slightly too wide.
548 Syntax errors for markup mode are confusing.
552 @subsubsection Nested scores
554 It is possible to nest music inside markups, by adding a
555 @code{\score} block to a markup expression. Such a score must
556 contain a @code{\layout} block.
558 @lilypond[quote,verbatim,ragged-right]
562 \relative { c4 d e f }
572 Snippets: @lsrdir{Text,Text}
574 @node Page wrapping text
575 @subsubsection Page wrapping text
577 Whereas @code{\markup} is used to enter a non-breakable block of
578 text, @code{\markuplines} can be used at top-level to enter lines
579 of text that can spread over multiple pages:
584 A very long text of justified lines.
588 An other very long paragraph.
595 @code{\markuplines} accepts a list of markup, that is either the
596 result of a markup list command, or a list of markups or of markup
597 lists. The built-in markup list commands are described in
598 @ref{Overview of text markup list commands}.
602 This manual: @ref{Overview of text markup list commands}, @ref{New
603 markup list command definition}.
605 Snippets: @lsrdir{Text,Text}
609 @funindex \markuplines
613 @subsubsection Font selection
615 @cindex font selection
616 @cindex font magnification
617 @funindex font-interface
619 By setting the object properties described below, you can select a
620 font from the preconfigured font families. LilyPond has default
621 support for the feta music fonts. Text fonts are selected through
622 Pango/FontConfig. The serif font defaults to New Century
623 Schoolbook, the sans and typewriter to whatever the Pango
624 installation defaults to.
628 @item @code{font-encoding}
629 is a symbol that sets layout of the glyphs. This should only be
630 set to select different types of non-text fonts, e.g.
632 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
633 standard music font, including ancient glyphs, @code{fetaDynamic}
634 for dynamic signs and @code{fetaNumber} for the number font.
636 @item @code{font-family}
637 is a symbol indicating the general class of the typeface.
638 Supported are @code{roman} (Computer Modern), @code{sans}, and
641 @item @code{font-shape}
642 is a symbol indicating the shape of the font. There are typically
643 several font shapes available for each font family. Choices are
644 @code{italic}, @code{caps}, and @code{upright}.
646 @item @code{font-series}
647 is a symbol indicating the series of the font. There are
648 typically several font series for each font family and shape.
649 Choices are @code{medium} and @code{bold}.
653 Fonts selected in the way sketched above come from a predefined
654 style sheet. If you want to use a font from outside the style
655 sheet, then set the @code{font-name} property,
657 @lilypond[fragment,verbatim]
659 \override Staff.TimeSignature #'font-name = #"Charter"
660 \override Staff.TimeSignature #'font-size = #2
663 \override #'(font-name . "Vera Bold")
664 { This text is in Vera Bold }
670 Any font can be used, as long as it is available to
671 Pango/FontConfig. To get a full list of all available fonts, run
675 lilypond -dshow-available-fonts blabla
678 (the last argument of the command can be anything, but has to be
682 The size of the font may be set with the @code{font-size}
683 property. The resulting size is taken relative to the
684 @code{text-font-size} as defined in the @code{\paper} block.
687 @cindex font magnification
690 It is also possible to change the default font family for the
691 entire document. This is done by calling the
692 @code{make-pango-font-tree} from within the @code{\paper} block.
693 The function takes names for the font families to use for roman,
694 sans serif and monospaced text. For example,
696 @cindex font families, setting
705 (make-pango-font-tree "Times New Roman"
712 c'^\markup { roman: foo \sans bla \typewriter bar }
716 @c we don't do Helvetica / Courier, since GS incorrectly loads
723 Snippets: @lsrdir{Text,Text}
726 @node Special text concerns
727 @subsection Special text concerns
729 @c FIXME: this section is to be removed
730 @c (see comments below) -vv
733 * New dynamic marks::
734 * Text and line spanners::
737 @node New dynamic marks
738 @subsubsection New dynamic marks
740 @c FIXME: this whole section should be removed and put in
741 @c "Writing text" -vv
743 It is possible to print new dynamic marks or text that should be
744 aligned with dynamics. Use @code{make-dynamic-script} to create
745 these marks. Note that the dynamic font only contains the
746 characters @code{f,m,p,r,s} and @code{z}.
748 Some situations (such as dynamic marks) have preset font-related
749 properties. If you are creating text in such situations, it is
750 advisable to cancel those properties with @code{normal-text}. See
751 @ref{Overview of text markup commands}, for more details.
753 @cindex make-dynamic-script
755 @lilypond[quote,verbatim,ragged-right]
756 sfzp = #(make-dynamic-script "sfzp")
762 @cindex Dynamics, editorial
763 @cindex Dynamics, parenthesis
765 It is also possible to print dynamics in round parenthesis or
766 square brackets. These are often used for adding editorial
769 @lilypond[quote,verbatim,ragged-right]
770 rndf = \markup{ \center-align {\line { \bold{\italic (}
771 \dynamic f \bold{\italic )} }} }
772 boxf = \markup{ \bracket { \dynamic f } }
773 { c'1_\rndf c'1_\boxf }
778 Snippets: @lsrdir{Text,Text}
781 @node Text and line spanners
782 @subsubsection Text and line spanners
784 @c FIXME: this whole section has to be removed.
785 @c glissando stuff should go into Expressive marks;
786 @c Text spanners should go into... Text spanners.
789 Some performance indications, e.g., @i{rallentando} and
790 @i{accelerando} and @i{trills} are written as text and are
791 extended over many measures with lines, sometimes dotted or wavy.
793 These all use the same routines as the glissando for drawing the
794 texts and the lines, and tuning their behavior is therefore also
795 done in the same way. It is done with a spanner, and the routine
796 responsible for drawing the spanners is
797 @code{ly:line-interface::print}. This routine determines the
798 exact location of the two @i{span points} and draws a line in
799 between, in the style requested.
801 Here is an example of the different line styles available, and how
804 @lilypond[relative=2,ragged-right,verbatim,fragment]
806 \once \override Glissando #'style = #'dashed-line
808 \override Glissando #'style = #'dotted-line
810 \override Glissando #'style = #'zigzag
812 \override Glissando #'style = #'trill
816 The information that determines the end-points is computed
817 on-the-fly for every graphic object, but it is possible to
820 @lilypond[relative=2,ragged-right,verbatim,fragment]
822 \once \override Glissando #'bound-details #'right #'Y = #-2
826 The @code{Glissando} object, like any other using the
827 @code{ly:line-interface::print} routine, carries a nested
828 association list. In the above statement, the value for @code{Y}
829 is set to @code{-2} for the association list corresponding to the
830 right end point. Of course, it is also possible to adjust the
831 left side with @code{left} instead of @code{right}.
833 If @code{Y} is not set, the value is computed from the vertical
834 position of right attachment point of the spanner.
836 In case of a line break, the values for the span-points are
837 extended with contents of the @code{left-broken} and
838 @code{right-broken} sublists, for example
840 @lilypond[relative=2,ragged-right,verbatim,fragment]
841 \override Glissando #'breakable = ##T
842 \override Glissando #'bound-details #'right-broken #'Y = #-3
847 The following properties can be used for the
851 This sets the Y-coordinate of the end point, in staff space. By
852 default, it is the center of the bound object, so for a glissando
853 it points to the vertical center of the note head.
855 For horizontal spanners, such as text spanner and trill spanners,
856 it is hardcoded to 0.
859 This determines where the line starts and ends in X-direction,
860 relative to the bound object. So, a value of @code{-1} (or
861 @code{LEFT}) makes the line start/end at the left side of the note
862 head it is attached to.
865 This is the absolute coordinate of the end point. It is usually
866 computed on the fly, and there is little use in overriding it.
869 Line spanners may have symbols at the beginning or end, which is
870 contained in this sub-property. This is for internal use, it is
871 recommended to use @code{text}.
874 This is a markup that is evaluated to yield stencil. It is used
875 to put @i{cresc.} and @i{tr} on horizontal spanners.
877 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
878 \override TextSpanner #'bound-details #'left #'text
879 = \markup { \small \bold Slower }
880 c2\startTextSpan b c a\stopTextSpan
883 @item stencil-align-dir-y
885 Without setting this, the stencil is simply put there at the
886 end-point, as defined by the @code{X} and @code{Y} sub properties.
887 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
888 will move the symbol at the edge relative to the end point of the
891 @lilypond[relative=1,fragment,verbatim]
892 \override TextSpanner #'bound-details
893 #'left #'stencil-align-dir-y = #DOWN
894 \override TextSpanner #'bound-details
895 #'right #'stencil-align-dir-y = #UP
897 \override TextSpanner #'bound-details
898 #'left #'text = #"gggg"
899 \override TextSpanner #'bound-details
900 #'right #'text = #"hhhh"
901 c4^\startTextSpan c c c \stopTextSpan
905 Setting this sub property to @code{#t} produce an arrowhead at the
909 This sub property controls the space between the specified
910 end-point of the line and the actual end. Without padding, a
911 glissando would start and end in the center of each note head.
915 TODO: add this somewhere
919 \override TextSpanner #'bound-details #'left-broken #'text = ##f
920 \override TextSpanner #'bound-details #'left #'text = \markup {
922 c'1 \startTextSpan \break
929 The music function \endSpanners terminates spanners and hairpins
930 after exactly one note.
932 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
938 When using \endSpanners it is not necessary to close
939 \startTextSpan with \stopTextSpan, nor is it necessary to close
946 Snippets: @lsrdir{Text,Text}
948 Internals Reference: @internalsref{TextSpanner},
949 @internalsref{Glissando}, @internalsref{VoiceFollower},
950 @internalsref{TrillSpanner},
951 @internalsref{line-spanner-interface}.