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 Some performance indications, e.g., @i{rallentando} or
158 @i{accelerando}, are written as text and are extended over many
159 measures with dotted lines.
161 Such objects, called @q{spanners}, may be created
162 from one note to another by using the following syntax:
164 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
165 \override TextSpanner #'bound-details #'left #'text = "rit."
171 The string to be printed is set through
172 object properties. By default it is printed in italic characters,
173 but different formatting can be obtained using
174 @code{\markup} blocks:
176 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
177 \override TextSpanner #'bound-details #'left #'text =
178 \markup { \upright "rit." }
183 The line style, as well as the text string, can be defined as an
184 object property. This syntax is described in @ref{Line styles}.
188 @funindex textSpannerUp
189 @code{\textSpannerUp},
190 @funindex textSpannerDown
191 @code{\textSpannerDown},
192 @funindex textSpannerNeutral
193 @code{\textSpannerNeutral}
197 Snippets: @lsrdir{Text,Text}
199 Internals Reference: @internalsref{TextSpanner}.
203 @subsubsection 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 Various text elements can be added to a score using
212 the syntax described in @ref{Rehearsal marks}:
214 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
215 c4\mark "dolce" c c c
218 This syntax makes possible to put any text on a bar line;
219 more complex text formatting may be added using a @code{\markup}
220 block, as described in @ref{Text markup}. This can be used to print
221 signs like coda, segno or fermata, by specifying the appropriate
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 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
246 {printing-marks-at-the-end-of-a-line-or-a-score.ly}
248 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
249 {aligning-marks-with-various-notation-objects.ly}
251 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
252 {printing-marks-on-every-staff.ly}
256 Snippets: @lsrdir{Text,Text}
258 Internals Reference: @internalsref{RehearsalMark}.
261 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
262 @c delete this sentence. -gp
263 @c A workaround is suggested in the first @snippets item -vv
265 If a mark is entered at the end of the last bar of the score (where
266 there is no next line), then the mark will not be printed at
270 @subsection Text markup
273 * Text markup introduction::
275 * Page wrapping text::
279 @node Text markup introduction
280 @subsubsection Text markup introduction
287 A @code{\markup} block is used to typeset text with an extensible syntax,
288 called @q{markup mode}.
289 Specific commands can be entered in this mode, using the
290 backslash @code{\} character.
291 @c TODO: move the following sentence (and add an example?) -vv
292 To @emph{print} such characters as
293 @code{\} and @code{#} in the output, use double
296 @lilypond[quote,verbatim,fragment,relative=1]
298 c1_\markup { hi there }
299 c1^\markup { hi \bold there, is \italic {anyone home?} }
300 c1_\markup { "\special {weird} #characters" }
304 An exhaustive list of @code{\markup}-specific commands can be found in
305 @ref{Text markup commands}.
307 @code{\markup} blocks can be used anywhere text is called,
308 and not only for @internalsref{TextScript}s objects.
310 @lilypond[quote,verbatim]
311 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
314 \override Score.RehearsalMark
315 #'break-visibility = #begin-of-line-invisible
316 \override Score.RehearsalMark #'self-alignment-X = #right
318 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
319 c2^\markup{ don't be \flat }
320 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
322 a2\mark \markup{ \large \bold Fine }
326 \addlyrics { bar, foo \markup{ \italic bar! } }
330 A @code{\markup} block can also be printed on its own at the top-level
331 of the input file, away from
332 any @code{\score} block. This syntax is described in
333 @ref{Multiple scores in a book}.
335 @lilypond[quote,ragged-right,verbatim]
336 \markup{ Here is some text. }
339 @cindex font switching
341 Some font switching commands are demonstrated here. Such commands
342 apply only to the first following word; several words may be affected
343 by enclosing them in braces.
346 \markup @{ \bold @{ hi there @} @}
349 @c TODO: remove the following line and example? -vv
351 For clarity, you can also do this for single arguments, e.g.,
354 \markup @{ is \italic @{ anyone @} home @}
357 The markup mode can be used to compose expressions, similar to
358 mathematical expressions, XML documents, and music expressions.
359 Such expressions can be vertically stacked, horizontally centered,
360 or aligned in different ways:
362 @lilypond[quote,verbatim,fragment,relative=1]
363 c1^\markup { \column { a bbbb \line { c d } } }
364 c1^\markup { \center-align { a bbbb c } }
365 c1^\markup { \line { a b c } }
368 Lists with no previous command are not kept distinct. In
369 the following example, the two @code{\markup} expressions
372 @c TODO: merge these two examples in a @lilypond example -vv
375 \center-align @{ @{ a b @} @{ c d @} @}
376 \center-align @{ a b c d @}
381 To keep lists of words distinct, please use quotes @code{"} or
382 the @code{\line} command
384 @lilypond[quote,verbatim,fragment,relative=1]
386 c4^\markup{ \center-align { on three lines } }
387 c4^\markup{ \center-align { "all one line" } }
388 c4^\markup{ \center-align { { on three lines } } }
389 c4^\markup{ \center-align { \line { on one line } } }
392 Markups can be stored in variables and these variables may be
393 attached to notes, like
396 allegro = \markup @{ \bold \large @{ Allegro @} @}
397 @{ a^\allegro b c d @}
400 Some objects have alignment procedures of their own, which cancel
401 out any effects of alignments applied to their markup arguments as
402 a whole. For example, the @internalsref{RehearsalMark} is
403 horizontally centered, so using @code{\mark \markup @{ \left-align
404 .. @}} has no effect.
406 In addition, vertical placement is performed after creating the
407 text markup object. If you wish to move an entire piece of
408 markup, you need to use the #'padding property or create an
409 @q{anchor} point inside the markup (generally with @code{\hspace
412 @lilypond[quote,verbatim,fragment,relative=1]
414 c'4^\markup{ \raise #5 "not raised" }
415 \once \override TextScript #'padding = #3
416 c'4^\markup{ raised }
417 c'4^\markup{ \hspace #0 \raise #1.5 raised }
420 Some situations (such as dynamic marks) have preset font-related
421 properties. If you are creating text in such situations, it is
422 advisable to cancel those properties with @code{normal-text}. See
423 @ref{Text markup commands}, for more details.
428 This manual: @ref{Text markup commands}.
430 Snippets: @lsrdir{Text,Text}
432 Internals Reference: @internalsref{TextScript}.
434 Init files: @file{scm/@/new@/-markup@/.scm}.
439 Kerning or generation of ligatures is only done when the @TeX{}
440 backend is used. In this case, LilyPond does not account for them
441 so texts will be spaced slightly too wide.
443 Syntax errors for markup mode are confusing.
447 @subsubsection Nested scores
449 It is possible to nest music inside markups, by adding a
450 @code{\score} block to a markup expression. Such a score must
451 contain a @code{\layout} block.
453 @lilypond[quote,verbatim,ragged-right]
457 \relative { c4 d e f }
467 Snippets: @lsrdir{Text,Text}
469 @node Page wrapping text
470 @subsubsection Page wrapping text
472 Whereas @code{\markup} is used to enter a non-breakable block of
473 text, @code{\markuplines} can be used at top-level to enter lines
474 of text that can spread over multiple pages:
479 A very long text of justified lines.
483 An other very long paragraph.
490 @code{\markuplines} accepts a list of markup, that is either the
491 result of a markup list command, or a list of markups or of markup
492 lists. The built-in markup list commands are described in
493 @ref{Text markup list commands}.
497 This manual: @ref{Text markup list commands}, @ref{New
498 markup list command definition}.
500 Snippets: @lsrdir{Text,Text}
504 @funindex \markuplines
508 @subsubsection Font selection
510 @cindex font selection
511 @cindex font magnification
512 @funindex font-interface
514 By setting the object properties described below, you can select a
515 font from the preconfigured font families. LilyPond has default
516 support for the feta music fonts. Text fonts are selected through
517 Pango/FontConfig. The serif font defaults to New Century
518 Schoolbook, the sans and typewriter to whatever the Pango
519 installation defaults to.
523 @item @code{font-encoding}
524 is a symbol that sets layout of the glyphs. This should only be
525 set to select different types of non-text fonts, e.g.
527 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
528 standard music font, including ancient glyphs, @code{fetaDynamic}
529 for dynamic signs and @code{fetaNumber} for the number font.
531 @item @code{font-family}
532 is a symbol indicating the general class of the typeface.
533 Supported are @code{roman} (Computer Modern), @code{sans}, and
536 @item @code{font-shape}
537 is a symbol indicating the shape of the font. There are typically
538 several font shapes available for each font family. Choices are
539 @code{italic}, @code{caps}, and @code{upright}.
541 @item @code{font-series}
542 is a symbol indicating the series of the font. There are
543 typically several font series for each font family and shape.
544 Choices are @code{medium} and @code{bold}.
548 Fonts selected in the way sketched above come from a predefined
549 style sheet. If you want to use a font from outside the style
550 sheet, then set the @code{font-name} property,
552 @lilypond[fragment,verbatim]
554 \override Staff.TimeSignature #'font-name = #"Charter"
555 \override Staff.TimeSignature #'font-size = #2
558 \override #'(font-name . "Vera Bold")
559 { This text is in Vera Bold }
565 Any font can be used, as long as it is available to
566 Pango/FontConfig. To get a full list of all available fonts, run
570 lilypond -dshow-available-fonts blabla
573 (the last argument of the command can be anything, but has to be
577 The size of the font may be set with the @code{font-size}
578 property. The resulting size is taken relative to the
579 @code{text-font-size} as defined in the @code{\paper} block.
582 @cindex font magnification
585 It is also possible to change the default font family for the
586 entire document. This is done by calling the
587 @code{make-pango-font-tree} from within the @code{\paper} block.
588 The function takes names for the font families to use for roman,
589 sans serif and monospaced text. For example,
591 @cindex font families, setting
600 (make-pango-font-tree "Times New Roman"
607 c'^\markup { roman: foo \sans bla \typewriter bar }
611 @c we don't do Helvetica / Courier, since GS incorrectly loads
618 Snippets: @lsrdir{Text,Text}