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 This section explains how to include text (with various
13 formatting) in your scores.
15 @cindex Text, other languages
16 To write accented and special text (such as characters from other
17 languages), simply insert the characters directly into the
18 lilypond file. The file must be saved as UTF-8. For more
19 information, see @ref{Text encoding}.
24 * Special text concerns::
29 @subsection Writing text
32 * Overview of text entry::
38 @node Overview of text entry
39 @unnumberedsubsubsec Overview of text entry
41 There are four ways to add text to scores:
45 @ref{Text scripts}: blah blah
47 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
52 @ref{Text spanners}: blah blah
54 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
56 \override TextSpanner #'bound-details #'left #'text =
57 \markup { \upright "rall" }
58 c2\startTextSpan b c\stopTextSpan a
62 @ref{Text marks}: blah blah
64 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
69 @ref{Vocal music}: blah blah, not in this section.
71 @lilypond[verbatim,quote,ragged-right]
73 \relative c'' { c4 c c c }
74 \addlyrics { one two three four }
82 Snippets: @lsrdir{text}
87 @unnumberedsubsubsec Text scripts
90 @cindex text items, non-empty
91 @cindex non-empty texts
93 It is possible to place arbitrary strings of text or @ref{Text
94 markup}, above or below notes by using a string @code{c^"text"}.
95 By default, these indications do not influence the note spacing,
96 but by using the command @code{\fatText}, the widths will be taken
99 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
100 c4^"longtext" \fatText c4_"longlongtext" c4
104 To prevent text from influencing spacing, use @code{\emptyText}.
106 More complex formatting may also be added to a note by using the
109 @lilypond[fragment,ragged-right,verbatim,quote]
110 c'4^\markup { bla \bold bla }
113 The @code{\markup} is described in more detail in @ref{Text
127 Checking to make sure that text scripts and lyrics are within the
128 margins is a relatively large computational task. To speed up
129 processing, lilypond does not perform such calculations by
130 default; to enable it, use
133 \override Score.PaperColumn #'keep-inside-line = ##t
139 Notation Reference: @ref{Text markup}.
141 Snippets: @lsrdir{text}
143 Internals Reference: @internalsref{TextScript}.
147 @unnumberedsubsubsec Text spanners
149 @cindex Text spanners
151 Some performance indications, e.g., @i{rallentando} or
152 @i{accelerando}, are written as text and are extended over many
153 measures with dotted lines. Such texts are created using text
154 spanners; attach @code{\startTextSpan} and @code{\stopTextSpan} to
155 the first and last notes of the spanner.
157 The string to be printed, as well as the style, is set through
160 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
163 \override TextSpanner #'bound-details #'left #'text =
164 \markup { \upright "rall" }
165 c2\startTextSpan b c\stopTextSpan a
168 \override TextSpanner #'bound-details #'left #'text =
169 \markup { \italic "rit" }
170 c2\startTextSpan b c\stopTextSpan a
175 @funindex textSpannerUp
176 @code{\textSpannerUp},
177 @funindex textSpannerDown
178 @code{\textSpannerDown},
179 @funindex textSpannerNeutral
180 @code{\textSpannerNeutral}.
185 To print a solid line, use
188 \override TextSpanner #'style = #'line
194 Snippets: @lsrdir{text}
196 Internals Reference: @internalsref{TextSpanner}.
200 @unnumberedsubsubsec Text marks
202 @cindex coda on bar line
203 @cindex segno on bar line
204 @cindex fermata on bar line
205 @cindex bar lines, symbols on
208 The @code{\mark} command is primarily used for @ref{Rehearsal
209 marks}, but it can also be used to put signs like coda, segno, and
210 fermata on a bar line. Use @code{\markup} to access the
211 appropriate symbol (symbols are listed in @ref{The Feta font}).
213 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
214 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
219 @code{\mark} is only typeset above the top stave of the score. If
220 you specify the @code{\mark} command at a bar line, the resulting
221 mark is placed above the bar line. If you specify it in the
222 middle of a bar, the resulting mark is positioned between notes.
223 If it is specified before the beginning of a score line, it is
224 placed before the first note of the line. Finally, if the mark
225 occurs at a line break, the mark will be printed at the beginning
228 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
229 @c delete this sentence. -gp
230 If there is no next line, then the mark will not be printed at
236 To print the mark at the end of the current line, use
239 \override Score.RehearsalMark
240 #'break-visibility = #begin-of-line-invisible
243 @code{\mark} is often useful for adding text to the end of bar.
244 In such cases, changing the @code{#'self-alignment} is very useful
246 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
247 \override Score.RehearsalMark
248 #'break-visibility = #begin-of-line-invisible
250 \once \override Score.RehearsalMark #'self-alignment-X = #right
251 \mark "D.S. al Fine "
254 Text marks may be aligned with notation objects other than bar
257 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
262 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
266 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
270 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
279 Possible symbols for the @code{break-align-symbols} list are
280 @code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
281 @code{staff-bar}, @code{left-edge}, @code{key-cancellation},
282 @code{key-signature}, and @code{time-signature}.
284 The text marks will, by default, be aligned with the middle of the
285 notation object, but this can be changed by overriding the
286 @code{break-align-anchor-alignment} and @code{break-align-anchor}
287 properties for the appropriate grob.
289 @lilypond[fragment,quote,ragged-right,verbatim]
291 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
295 % the RehearsalMark will be aligned with the left edge of the KeySignature
296 \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT
301 % the RehearsalMark will be aligned with the right edge of the KeySignature
302 \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT
307 % the RehearsalMark will be aligned with the left edge of the KeySignature
308 % and then shifted right by 2 units.
309 \once \override Staff.KeySignature #'break-align-anchor = #2
315 Although text marks are normally only printed above the topmost
316 staff, you may alter this to print them on every staff,
318 @lilypond[quote,ragged-right,verbatim,relative=2]
321 \remove "Mark_engraver"
325 \consists "Mark_engraver"
327 { c''1 \mark "foo" c'' }
329 \consists "Mark_engraver"
331 { c'1 \mark "foo" c' }
339 Snippets: @lsrdir{text}
341 Internals Reference: @internalsref{RehearsalMark}.
346 @subsection Text markup
349 * Text markup introduction::
351 * Page wrapping text::
355 @node Text markup introduction
356 @unnumberedsubsubsec Text markup introduction
363 Use @code{\markup} to typeset text. Commands are entered with the
364 backslash @code{\}. To enter @code{\} and @code{#}, use double
367 @lilypond[quote,verbatim,fragment,relative=1]
369 c1_\markup { hi there }
370 c1^\markup { hi \bold there, is \italic {anyone home?} }
371 c1_\markup { "\special {weird} #characters" }
375 See @ref{Overview of text markup commands}, for a list of all
378 @code{\markup} is primarily used for @internalsref{TextScript}s,
379 but it can also be used anywhere text is called in lilypond
381 @lilypond[quote,verbatim]
382 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
385 \override Score.RehearsalMark
386 #'break-visibility = #begin-of-line-invisible
387 \override Score.RehearsalMark #'self-alignment-X = #right
389 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
390 c2^\markup{ don't be \flat }
391 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
393 a2\mark \markup{ \large \bold Fine }
397 \addlyrics { bar, foo \markup{ \italic bar! } }
401 A @code{\markup} command can also be placed on its own, away from
402 any @code{\score} block, see @ref{Multiple scores in a book}.
404 @lilypond[quote,ragged-right,verbatim]
405 \markup{ Here is some text. }
408 @cindex font switching
410 The markup in the example demonstrates font switching commands.
411 The command @code{\bold} and @code{\italic} apply to the first
412 following word only; to apply a command to more than one word,
413 enclose the words with braces,
416 \markup @{ \bold @{ hi there @} @}
420 For clarity, you can also do this for single arguments, e.g.,
423 \markup @{ is \italic @{ anyone @} home @}
426 In markup mode you can compose expressions, similar to
427 mathematical expressions, XML documents, and music expressions.
428 You can stack expressions grouped vertically with the command
429 @code{\column}. Similarly, @code{\center-align} aligns texts by
432 @lilypond[quote,verbatim,fragment,relative=1]
433 c1^\markup { \column { a bbbb \line { c d } } }
434 c1^\markup { \center-align { a bbbb c } }
435 c1^\markup { \line { a b c } }
438 Lists with no previous command are not kept distinct. The
442 \center-align @{ @{ a b @} @{ c d @} @}
450 \center-align @{ a b c d @}
455 To keep lists of words distinct, please use quotes @code{"} or
456 the @code{\line} command
458 @lilypond[quote,verbatim,fragment,relative=1]
460 c4^\markup{ \center-align { on three lines } }
461 c4^\markup{ \center-align { "all one line" } }
462 c4^\markup{ \center-align { { on three lines } } }
463 c4^\markup{ \center-align { \line { on one line } } }
466 Markups can be stored in variables and these variables may be
467 attached to notes, like
470 allegro = \markup @{ \bold \large @{ Allegro @} @}
471 @{ a^\allegro b c d @}
474 Some objects have alignment procedures of their own, which cancel
475 out any effects of alignments applied to their markup arguments as
476 a whole. For example, the @internalsref{RehearsalMark} is
477 horizontally centered, so using @code{\mark \markup @{ \left-align
478 .. @}} has no effect.
480 In addition, vertical placement is performed after creating the
481 text markup object. If you wish to move an entire piece of
482 markup, you need to use the #'padding property or create an
483 @q{anchor} point inside the markup (generally with @code{\hspace
486 @lilypond[quote,verbatim,fragment,relative=1]
488 c'4^\markup{ \raise #5 "not raised" }
489 \once \override TextScript #'padding = #3
490 c'4^\markup{ raised }
491 c'4^\markup{ \hspace #0 \raise #1.5 raised }
494 Some situations (such as dynamic marks) have preset font-related
495 properties. If you are creating text in such situations, it is
496 advisable to cancel those properties with @code{normal-text}. See
497 @ref{Overview of text markup commands}, for more details.
502 This manual: @ref{Overview of text markup commands}.
504 Snippets: @lsrdir{text}
506 Internals Reference: @internalsref{TextScript}.
508 Init files: @file{scm/@/new@/-markup@/.scm}.
513 Kerning or generation of ligatures is only done when the @TeX{}
514 backend is used. In this case, LilyPond does not account for them
515 so texts will be spaced slightly too wide.
517 Syntax errors for markup mode are confusing.
521 @unnumberedsubsubsec Nested scores
523 It is possible to nest music inside markups, by adding a
524 @code{\score} block to a markup expression. Such a score must
525 contain a @code{\layout} block.
527 @lilypond[quote,verbatim,ragged-right]
531 \relative { c4 d e f }
541 Snippets: @lsrdir{text}
543 @node Page wrapping text
544 @unnumberedsubsubsec Page wrapping text
546 Whereas @code{\markup} is used to enter a non-breakable block of
547 text, @code{\markuplines} can be used at top-level to enter lines
548 of text that can spread over multiple pages:
553 A very long text of justified lines.
557 An other very long paragraph.
564 @code{\markuplines} accepts a list of markup, that is either the
565 result of a markup list command, or a list of markups or of markup
566 lists. The built-in markup list commands are described in
567 @ref{Overview of text markup list commands}.
571 This manual: @ref{Overview of text markup list commands}, @ref{New
572 markup list command definition}.
574 Snippets: @lsrdir{text}
578 @funindex \markuplines
582 @unnumberedsubsubsec Font selection
584 @cindex font selection
585 @cindex font magnification
586 @funindex font-interface
588 By setting the object properties described below, you can select a
589 font from the preconfigured font families. LilyPond has default
590 support for the feta music fonts. Text fonts are selected through
591 Pango/FontConfig. The serif font defaults to New Century
592 Schoolbook, the sans and typewriter to whatever the Pango
593 installation defaults to.
597 @item @code{font-encoding}
598 is a symbol that sets layout of the glyphs. This should only be
599 set to select different types of non-text fonts, e.g.
601 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
602 standard music font, including ancient glyphs, @code{fetaDynamic}
603 for dynamic signs and @code{fetaNumber} for the number font.
605 @item @code{font-family}
606 is a symbol indicating the general class of the typeface.
607 Supported are @code{roman} (Computer Modern), @code{sans}, and
610 @item @code{font-shape}
611 is a symbol indicating the shape of the font. There are typically
612 several font shapes available for each font family. Choices are
613 @code{italic}, @code{caps}, and @code{upright}.
615 @item @code{font-series}
616 is a symbol indicating the series of the font. There are
617 typically several font series for each font family and shape.
618 Choices are @code{medium} and @code{bold}.
622 Fonts selected in the way sketched above come from a predefined
623 style sheet. If you want to use a font from outside the style
624 sheet, then set the @code{font-name} property,
626 @lilypond[fragment,verbatim]
628 \override Staff.TimeSignature #'font-name = #"Charter"
629 \override Staff.TimeSignature #'font-size = #2
632 \override #'(font-name . "Vera Bold")
633 { This text is in Vera Bold }
639 Any font can be used, as long as it is available to
640 Pango/FontConfig. To get a full list of all available fonts, run
644 lilypond -dshow-available-fonts blabla
647 (the last argument of the command can be anything, but has to be
651 The size of the font may be set with the @code{font-size}
652 property. The resulting size is taken relative to the
653 @code{text-font-size} as defined in the @code{\paper} block.
656 @cindex font magnification
659 It is also possible to change the default font family for the
660 entire document. This is done by calling the
661 @code{make-pango-font-tree} from within the @code{\paper} block.
662 The function takes names for the font families to use for roman,
663 sans serif and monospaced text. For example,
665 @cindex font families, setting
674 (make-pango-font-tree "Times New Roman"
681 c'^\markup { roman: foo \sans bla \typewriter bar }
685 @c we don't do Helvetica / Courier, since GS incorrectly loads
692 Snippets: @lsrdir{text}
695 @node Special text concerns
696 @subsection Special text concerns
701 * New dynamic marks::
702 * Text and line spanners::
705 @node New dynamic marks
706 @unnumberedsubsubsec New dynamic marks
708 It is possible to print new dynamic marks or text that should be
709 aligned with dynamics. Use @code{make-dynamic-script} to create
710 these marks. Note that the dynamic font only contains the
711 characters @code{f,m,p,r,s} and @code{z}.
713 Some situations (such as dynamic marks) have preset font-related
714 properties. If you are creating text in such situations, it is
715 advisable to cancel those properties with @code{normal-text}. See
716 @ref{Overview of text markup commands}, for more details.
718 @cindex make-dynamic-script
720 @lilypond[quote,verbatim,ragged-right]
721 sfzp = #(make-dynamic-script "sfzp")
727 @cindex Dynamics, editorial
728 @cindex Dynamics, parenthesis
730 It is also possible to print dynamics in round parenthesis or
731 square brackets. These are often used for adding editorial
734 @lilypond[quote,verbatim,ragged-right]
735 rndf = \markup{ \center-align {\line { \bold{\italic (}
736 \dynamic f \bold{\italic )} }} }
737 boxf = \markup{ \bracket { \dynamic f } }
738 { c'1_\rndf c'1_\boxf }
743 Snippets: @lsrdir{text}
746 @node Text and line spanners
747 @unnumberedsubsubsec Text and line spanners
749 Some performance indications, e.g., @i{rallentando} and
750 @i{accelerando} and @i{trills} are written as text and are
751 extended over many measures with lines, sometimes dotted or wavy.
753 These all use the same routines as the glissando for drawing the
754 texts and the lines, and tuning their behavior is therefore also
755 done in the same way. It is done with a spanner, and the routine
756 responsible for drawing the spanners is
757 @code{ly:line-interface::print}. This routine determines the
758 exact location of the two @i{span points} and draws a line in
759 between, in the style requested.
761 Here is an example of the different line styles available, and how
764 @lilypond[relative=2,ragged-right,verbatim,fragment]
766 \once \override Glissando #'style = #'dashed-line
768 \override Glissando #'style = #'dotted-line
770 \override Glissando #'style = #'zigzag
772 \override Glissando #'style = #'trill
776 The information that determines the end-points is computed
777 on-the-fly for every graphic object, but it is possible to
780 @lilypond[relative=2,ragged-right,verbatim,fragment]
782 \once \override Glissando #'bound-details #'right #'Y = #-2
786 The @code{Glissando} object, like any other using the
787 @code{ly:line-interface::print} routine, carries a nested
788 association list. In the above statement, the value for @code{Y}
789 is set to @code{-2} for the association list corresponding to the
790 right end point. Of course, it is also possible to adjust the
791 left side with @code{left} instead of @code{right}.
793 If @code{Y} is not set, the value is computed from the vertical
794 position of right attachment point of the spanner.
796 In case of a line break, the values for the span-points are
797 extended with contents of the @code{left-broken} and
798 @code{right-broken} sublists, for example
800 @lilypond[relative=2,ragged-right,verbatim,fragment]
801 \override Glissando #'breakable = ##T
802 \override Glissando #'bound-details #'right-broken #'Y = #-3
807 The following properties can be used for the
811 This sets the Y-coordinate of the end point, in staff space. By
812 default, it is the center of the bound object, so for a glissando
813 it points to the vertical center of the note head.
815 For horizontal spanners, such as text spanner and trill spanners,
816 it is hardcoded to 0.
819 This determines where the line starts and ends in X-direction,
820 relative to the bound object. So, a value of @code{-1} (or
821 @code{LEFT}) makes the line start/end at the left side of the note
822 head it is attached to.
825 This is the absolute coordinate of the end point. It is usually
826 computed on the fly, and there is little use in overriding it.
829 Line spanners may have symbols at the beginning or end, which is
830 contained in this sub-property. This is for internal use, it is
831 recommended to use @code{text}.
834 This is a markup that is evaluated to yield stencil. It is used
835 to put @i{cresc.} and @i{tr} on horizontal spanners.
837 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
838 \override TextSpanner #'bound-details #'left #'text
839 = \markup { \small \bold Slower }
840 c2\startTextSpan b c a\stopTextSpan
843 @item stencil-align-dir-y
845 Without setting this, the stencil is simply put there at the
846 end-point, as defined by the @code{X} and @code{Y} sub properties.
847 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
848 will move the symbol at the edge relative to the end point of the
851 @lilypond[relative=1,fragment,verbatim]
852 \override TextSpanner #'bound-details
853 #'left #'stencil-align-dir-y = #DOWN
854 \override TextSpanner #'bound-details
855 #'right #'stencil-align-dir-y = #UP
857 \override TextSpanner #'bound-details
858 #'left #'text = #"gggg"
859 \override TextSpanner #'bound-details
860 #'right #'text = #"hhhh"
861 c4^\startTextSpan c c c \stopTextSpan
865 Setting this sub property to @code{#t} produce an arrowhead at the
869 This sub property controls the space between the specified
870 end-point of the line and the actual end. Without padding, a
871 glissando would start and end in the center of each note head.
875 TODO: add this somewhere
879 \override TextSpanner #'bound-details #'left-broken #'text = ##f
880 \override TextSpanner #'bound-details #'left #'text = \markup {
882 c'1 \startTextSpan \break
889 The music function \endSpanners terminates spanners and hairpins
890 after exactly one note.
892 @lilypond[verbatim,quote,raged-right,relative=2,fragment]
898 When using \endSpanners it is not necessary to close
899 \startTextSpan with \stopTextSpan, nor is it necessary to close
906 Snippets: @lsrdir{text}
908 Internals Reference: @internalsref{TextSpanner},
909 @internalsref{Glissando}, @internalsref{VoiceFollower},
910 @internalsref{TrillSpanner},
911 @internalsref{line-spanner-interface}.