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}.}
30 @subsection Writing text
33 * Overview of text entry::
39 @node Overview of text entry
40 @subsubsection Overview of text entry
42 There are four ways to add text to scores:
46 @ref{Text scripts}: blah blah
48 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
53 @ref{Text spanners}: blah blah
55 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
57 \override TextSpanner #'bound-details #'left #'text =
58 \markup { \upright "rall" }
59 c2\startTextSpan b c\stopTextSpan a
63 @ref{Text marks}: blah blah
65 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
70 @ref{Vocal music}: blah blah, not in this section.
72 @lilypond[verbatim,quote,ragged-right]
74 \relative c'' { c4 c c c }
75 \addlyrics { one two three four }
83 Snippets: @lsrdir{Text,Text}
88 @subsubsection Text scripts
91 @cindex text items, non-empty
92 @cindex non-empty texts
94 It is possible to add arbitrary text indications with
95 @var{note}@code{-"}@var{text}@code{"}.
96 Such indications can also be manually placed
97 above or below the staff, using the
98 simple syntax described in @ref{Controlling direction and
101 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
102 d8^"pizz." e f g a4-"scherz." f
105 In LilyPond, such text strings are called @command{markup}
106 objects. This syntax is actually a shorthand; more complex text
107 formatting may be added to a note by explicitly using the
108 @code{\markup} command, as described in @ref{Text markup}.
110 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
111 d8^\markup { \italic pizz. } e f g
112 a4_\markup { \tiny scherz. \bold molto } f
115 By default, text indications do not influence the note spacing.
116 However, their widths can be taken into account:
117 in the following example, the first text string does not affect
118 spacing, whereas the second one does.
120 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
121 d8^"pizz." e f g \textLengthOn a4_"scherzando" f
126 @funindex \textLengthOn
127 @code{\textLengthOn},
128 @funindex \textLengthOff
129 @code{\textLengthOff}.
134 Notation Reference: @ref{Text markup}.
136 Snippets: @lsrdir{Text,Text}
138 Internals Reference: @internalsref{TextScript}.
142 Checking to make sure that text scripts and lyrics are within the
143 margins is a relatively large computational task. To speed up
144 processing, LilyPond does not perform such calculations by
145 default; to enable it, use
148 \override Score.PaperColumn #'keep-inside-line = ##t
153 @subsubsection Text spanners
155 @cindex Text spanners
157 @c TODO: merge these explanations with the ones below in
158 @c "Text and Line spanners" -vv
160 Some performance indications, e.g., @i{rallentando} or
161 @i{accelerando}, are written as text and are extended over many
162 measures with dotted lines; you can create such text spanners
163 from one note to another by using the following syntax:
165 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
166 \override TextSpanner #'bound-details #'left #'text = "rit."
172 The string to be printed is set through
173 object properties. By default it is printed in italic characters,
174 but different formatting can be obtained using
175 @code{\markup} blocks:
177 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
178 \override TextSpanner #'bound-details #'left #'text =
179 \markup { \upright "rit." }
186 @funindex textSpannerUp
187 @code{\textSpannerUp},
188 @funindex textSpannerDown
189 @code{\textSpannerDown},
190 @funindex textSpannerNeutral
191 @code{\textSpannerNeutral}.
193 The line style, as well as the text string, can be defined as an
194 object property. This syntax is described in @ref{Line styles}.
199 Snippets: @lsrdir{Text,Text}
201 Internals Reference: @internalsref{TextSpanner}.
205 @subsubsection Text marks
207 @cindex coda on bar line
208 @cindex segno on bar line
209 @cindex fermata on bar line
210 @cindex bar lines, symbols on
213 Various text elements can be added to a score using
214 the syntax described in @ref{Rehearsal marks}:
216 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
217 c4\mark "dolce" c c c
220 This syntax makes possible to put any text on a bar line, but also
221 signs like coda, segno, or fermata, by specifying the appropriate
222 symbol name. These symbols are listed in @ref{The Feta font}.
224 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
225 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
230 Such objects are only typeset above the top staff of the score; they
231 can be placed above the bar line or between notes, depending on whether
232 you specify it at the end or the middle of a bar. When specified at the
233 beginning of a score or at a line break, the mark will be printed at
234 the beginning of the line (the next line, in case of a line break).
236 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
238 c\mark "assai" \break
245 @c TODO: to be LSR-ized stuff -vv
247 To print the mark at the end of the current line, use
250 \override Score.RehearsalMark
251 #'break-visibility = #begin-of-line-invisible
254 @code{\mark} is often useful for adding text to the end of bar.
255 In such cases, changing the @code{#'self-alignment} is very useful
257 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
258 \override Score.RehearsalMark
259 #'break-visibility = #begin-of-line-invisible
261 \once \override Score.RehearsalMark #'self-alignment-X = #right
262 \mark "D.S. al Fine "
265 If specified, text marks may be aligned with notation objects
266 other than bar lines. These objects include @code{ambitus},
267 @code{breathing-sign}, @code{clef}, @code{custos},
268 @code{staff-bar}, @code{left-edge}, @code{key-cancellation},
269 @code{key-signature}, and @code{time-signature}.
272 In such cases, text marks will be horizontally centered
273 above the object. However this can be changed, as demonstrated
274 on the second line of this example (in a score with multiple staves,
275 this setting should be done for all the staves).
278 @lilypond[fragment,quote,ragged-right,verbatim,relative=1]
281 % the RehearsalMark will be centered above the Clef
282 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
288 % the RehearsalMark will be centered above the TimeSignature
289 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
296 % the RehearsalMark will be centered above the KeySignature
297 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
307 % the RehearsalMark will be aligned with the left edge of the KeySignature
308 \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
313 % the RehearsalMark will be aligned with the right edge of the KeySignature
314 \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
319 % the RehearsalMark will be aligned with the left edge of the KeySignature
320 % and then shifted right by 1 unit.
321 \once \override Score.KeySignature #'break-align-anchor = #1
327 Although text marks are normally only printed above the topmost
328 staff, you may alter this to print them on every staff:
330 @lilypond[quote,ragged-right,verbatim,relative=2]
333 \remove "Mark_engraver"
337 \consists "Mark_engraver"
339 { c''1 \mark "foo" c'' }
341 \consists "Mark_engraver"
343 { c'1 \mark "foo" c' }
351 Snippets: @lsrdir{Text,Text}
353 Internals Reference: @internalsref{RehearsalMark}.
356 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
357 @c delete this sentence. -gp
359 If a mark is entered at the end of the last bar of the score (where
360 there is no next line), then the mark will not be printed at
364 @subsection Text markup
367 * Text markup introduction::
369 * Page wrapping text::
373 @node Text markup introduction
374 @subsubsection Text markup introduction
381 A @code{\markup} block is used to typeset text with an extensible syntax,
382 called @q{markup mode}.
383 Specific commands can be entered in this mode, using the
384 backslash @code{\} character.
385 @c TODO: move the following sentence (and add an example?) -vv
386 To @emph{print} such characters as
387 @code{\} and @code{#} in the output, use double
390 @lilypond[quote,verbatim,fragment,relative=1]
392 c1_\markup { hi there }
393 c1^\markup { hi \bold there, is \italic {anyone home?} }
394 c1_\markup { "\special {weird} #characters" }
398 An exhaustive list of @code{\markup}-specific commands can be found in
399 @ref{Text markup commands}.
401 @code{\markup} blocks can be used anywhere text is called,
402 and not only for @internalsref{TextScript}s objects.
404 @lilypond[quote,verbatim]
405 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
408 \override Score.RehearsalMark
409 #'break-visibility = #begin-of-line-invisible
410 \override Score.RehearsalMark #'self-alignment-X = #right
412 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
413 c2^\markup{ don't be \flat }
414 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
416 a2\mark \markup{ \large \bold Fine }
420 \addlyrics { bar, foo \markup{ \italic bar! } }
424 A @code{\markup} block can also be printed on its own at the top-level
425 of the input file, away from
426 any @code{\score} block. This syntax is described in
427 @ref{Multiple scores in a book}.
429 @lilypond[quote,ragged-right,verbatim]
430 \markup{ Here is some text. }
433 @cindex font switching
435 Some font switching commands are demonstrated here. Such commands
436 apply only to the first following word; several words may be affected
437 by enclosing them in braces.
440 \markup @{ \bold @{ hi there @} @}
443 @c TODO: remove the following line and example? -vv
445 For clarity, you can also do this for single arguments, e.g.,
448 \markup @{ is \italic @{ anyone @} home @}
451 The markup mode can be used to compose expressions, similar to
452 mathematical expressions, XML documents, and music expressions.
453 Such expressions can be vertically stacked, horizontally centered,
454 or aligned in different ways:
456 @lilypond[quote,verbatim,fragment,relative=1]
457 c1^\markup { \column { a bbbb \line { c d } } }
458 c1^\markup { \center-align { a bbbb c } }
459 c1^\markup { \line { a b c } }
462 Lists with no previous command are not kept distinct. In
463 the following example, the two @code{\markup} expressions
466 @c TODO: merge these two examples in a @lilypond example -vv
469 \center-align @{ @{ a b @} @{ c d @} @}
470 \center-align @{ a b c d @}
475 To keep lists of words distinct, please use quotes @code{"} or
476 the @code{\line} command
478 @lilypond[quote,verbatim,fragment,relative=1]
480 c4^\markup{ \center-align { on three lines } }
481 c4^\markup{ \center-align { "all one line" } }
482 c4^\markup{ \center-align { { on three lines } } }
483 c4^\markup{ \center-align { \line { on one line } } }
486 Markups can be stored in variables and these variables may be
487 attached to notes, like
490 allegro = \markup @{ \bold \large @{ Allegro @} @}
491 @{ a^\allegro b c d @}
494 Some objects have alignment procedures of their own, which cancel
495 out any effects of alignments applied to their markup arguments as
496 a whole. For example, the @internalsref{RehearsalMark} is
497 horizontally centered, so using @code{\mark \markup @{ \left-align
498 .. @}} has no effect.
500 In addition, vertical placement is performed after creating the
501 text markup object. If you wish to move an entire piece of
502 markup, you need to use the #'padding property or create an
503 @q{anchor} point inside the markup (generally with @code{\hspace
506 @lilypond[quote,verbatim,fragment,relative=1]
508 c'4^\markup{ \raise #5 "not raised" }
509 \once \override TextScript #'padding = #3
510 c'4^\markup{ raised }
511 c'4^\markup{ \hspace #0 \raise #1.5 raised }
514 Some situations (such as dynamic marks) have preset font-related
515 properties. If you are creating text in such situations, it is
516 advisable to cancel those properties with @code{normal-text}. See
517 @ref{Text markup commands}, for more details.
522 This manual: @ref{Text markup commands}.
524 Snippets: @lsrdir{Text,Text}
526 Internals Reference: @internalsref{TextScript}.
528 Init files: @file{scm/@/new@/-markup@/.scm}.
533 Kerning or generation of ligatures is only done when the @TeX{}
534 backend is used. In this case, LilyPond does not account for them
535 so texts will be spaced slightly too wide.
537 Syntax errors for markup mode are confusing.
541 @subsubsection Nested scores
543 It is possible to nest music inside markups, by adding a
544 @code{\score} block to a markup expression. Such a score must
545 contain a @code{\layout} block.
547 @lilypond[quote,verbatim,ragged-right]
551 \relative { c4 d e f }
561 Snippets: @lsrdir{Text,Text}
563 @node Page wrapping text
564 @subsubsection Page wrapping text
566 Whereas @code{\markup} is used to enter a non-breakable block of
567 text, @code{\markuplines} can be used at top-level to enter lines
568 of text that can spread over multiple pages:
573 A very long text of justified lines.
577 An other very long paragraph.
584 @code{\markuplines} accepts a list of markup, that is either the
585 result of a markup list command, or a list of markups or of markup
586 lists. The built-in markup list commands are described in
587 @ref{Text markup list commands}.
591 This manual: @ref{Text markup list commands}, @ref{New
592 markup list command definition}.
594 Snippets: @lsrdir{Text,Text}
598 @funindex \markuplines
602 @subsubsection Font selection
604 @cindex font selection
605 @cindex font magnification
606 @funindex font-interface
608 By setting the object properties described below, you can select a
609 font from the preconfigured font families. LilyPond has default
610 support for the feta music fonts. Text fonts are selected through
611 Pango/FontConfig. The serif font defaults to New Century
612 Schoolbook, the sans and typewriter to whatever the Pango
613 installation defaults to.
617 @item @code{font-encoding}
618 is a symbol that sets layout of the glyphs. This should only be
619 set to select different types of non-text fonts, e.g.
621 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
622 standard music font, including ancient glyphs, @code{fetaDynamic}
623 for dynamic signs and @code{fetaNumber} for the number font.
625 @item @code{font-family}
626 is a symbol indicating the general class of the typeface.
627 Supported are @code{roman} (Computer Modern), @code{sans}, and
630 @item @code{font-shape}
631 is a symbol indicating the shape of the font. There are typically
632 several font shapes available for each font family. Choices are
633 @code{italic}, @code{caps}, and @code{upright}.
635 @item @code{font-series}
636 is a symbol indicating the series of the font. There are
637 typically several font series for each font family and shape.
638 Choices are @code{medium} and @code{bold}.
642 Fonts selected in the way sketched above come from a predefined
643 style sheet. If you want to use a font from outside the style
644 sheet, then set the @code{font-name} property,
646 @lilypond[fragment,verbatim]
648 \override Staff.TimeSignature #'font-name = #"Charter"
649 \override Staff.TimeSignature #'font-size = #2
652 \override #'(font-name . "Vera Bold")
653 { This text is in Vera Bold }
659 Any font can be used, as long as it is available to
660 Pango/FontConfig. To get a full list of all available fonts, run
664 lilypond -dshow-available-fonts blabla
667 (the last argument of the command can be anything, but has to be
671 The size of the font may be set with the @code{font-size}
672 property. The resulting size is taken relative to the
673 @code{text-font-size} as defined in the @code{\paper} block.
676 @cindex font magnification
679 It is also possible to change the default font family for the
680 entire document. This is done by calling the
681 @code{make-pango-font-tree} from within the @code{\paper} block.
682 The function takes names for the font families to use for roman,
683 sans serif and monospaced text. For example,
685 @cindex font families, setting
694 (make-pango-font-tree "Times New Roman"
701 c'^\markup { roman: foo \sans bla \typewriter bar }
705 @c we don't do Helvetica / Courier, since GS incorrectly loads
712 Snippets: @lsrdir{Text,Text}