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.
18 @cindex Text, other languages
19 @warning{To write accented and special text (such as characters
20 from other languages), simply insert the characters directly into
21 the LilyPond file. The file must be saved as UTF-8. For more
22 information, see @ref{Text encoding}.}
31 @subsection Writing text
41 @subsubsection Text scripts
44 @cindex text items, non-empty
45 @cindex non-empty texts
47 It is possible to add arbitrary text indications with
48 @var{note}@code{-"}@var{text}@code{"}.
49 Such indications can also be manually placed
50 above or below the staff, using the
51 simple syntax described in @ref{Controlling direction and
54 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
55 d8^"pizz." e f g a4-"scherz." f
58 In LilyPond, such text strings are called @command{markup}
59 objects. This syntax is actually a shorthand; more complex text
60 formatting may be added to a note by explicitly using the
61 @code{\markup} command, as described in @ref{Text markup}.
63 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
64 d8^\markup { \italic pizz. } e f g
65 a4_\markup { \tiny scherz. \bold molto } f
68 By default, text indications do not influence the note spacing.
69 However, their widths can be taken into account:
70 in the following example, the first text string does not affect
71 spacing, whereas the second one does.
73 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
74 d8^"pizz." e f g \textLengthOn a4_"scherzando" f
79 @funindex \textLengthOn
81 @funindex \textLengthOff
87 Notation Reference: @ref{Text markup}.
89 Snippets: @lsrdir{Text,Text}
91 Internals Reference: @internalsref{TextScript}.
95 Checking to make sure that text scripts and lyrics are within the
96 margins is a relatively large computational task. To speed up
97 processing, LilyPond does not perform such calculations by
98 default; to enable it, use
101 \override Score.PaperColumn #'keep-inside-line = ##t
106 @subsubsection Text spanners
108 @cindex Text spanners
110 Some performance indications, e.g., @i{rallentando} or
111 @i{accelerando}, are written as text and are extended over many
112 measures with dotted lines.
114 Such objects, called @q{spanners}, may be created
115 from one note to another by using the following syntax:
117 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
118 \override TextSpanner #'bound-details #'left #'text = "rit."
124 The string to be printed is set through
125 object properties. By default it is printed in italic characters,
126 but different formatting can be obtained using
127 @code{\markup} blocks:
129 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
130 \override TextSpanner #'bound-details #'left #'text =
131 \markup { \upright "rit." }
136 The line style, as well as the text string, can be defined as an
137 object property. This syntax is described in @ref{Line styles}.
141 @funindex textSpannerUp
142 @code{\textSpannerUp},
143 @funindex textSpannerDown
144 @code{\textSpannerDown},
145 @funindex textSpannerNeutral
146 @code{\textSpannerNeutral}
150 Snippets: @lsrdir{Text,Text}
152 Internals Reference: @internalsref{TextSpanner}.
156 @subsubsection Text marks
158 @cindex coda on bar line
159 @cindex segno on bar line
160 @cindex fermata on bar line
161 @cindex bar lines, symbols on
164 Various text elements can be added to a score using
165 the syntax described in @ref{Rehearsal marks}:
167 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
168 c4\mark "dolce" c c c
171 This syntax makes possible to put any text on a bar line;
172 more complex text formatting may be added using a @code{\markup}
173 block, as described in @ref{Text markup}. This can be used to print
174 signs like coda, segno or fermata, by specifying the appropriate
177 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
178 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
183 Such objects are only typeset above the top staff of the score; they
184 can be placed above the bar line or between notes, depending on whether
185 you specify it at the end or the middle of a bar. When specified at the
186 beginning of a score or at a line break, the mark will be printed at
187 the beginning of the line (the next line, in case of a line break).
189 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
191 c\mark "assai" \break
198 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
199 {printing-marks-at-the-end-of-a-line-or-a-score.ly}
201 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
202 {aligning-marks-with-various-notation-objects.ly}
204 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
205 {printing-marks-on-every-staff.ly}
209 Snippets: @lsrdir{Text,Text}
211 Internals Reference: @internalsref{RehearsalMark}.
214 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
215 @c delete this sentence. -gp
216 @c A workaround is suggested in the first @snippets item -vv
218 If a mark is entered at the end of the last bar of the score (where
219 there is no next line), then the mark will not be printed at
223 @subsection Text markup
226 * Text markup introduction::
228 * Page wrapping text::
232 @node Text markup introduction
233 @subsubsection Text markup introduction
240 A @code{\markup} block is used to typeset text with an extensible syntax,
241 called @q{markup mode}.
242 Specific commands can be entered in this mode, using the
243 backslash @code{\} character.
244 @c TODO: move the following sentence (and add an example?) -vv
245 To @emph{print} such characters as
246 @code{\} and @code{#} in the output, use double
249 @lilypond[quote,verbatim,fragment,relative=1]
251 c1_\markup { hi there }
252 c1^\markup { hi \bold there, is \italic {anyone home?} }
253 c1_\markup { "\special {weird} #characters" }
257 An exhaustive list of @code{\markup}-specific commands can be found in
258 @ref{Text markup commands}.
260 @code{\markup} blocks can be used anywhere text is called,
261 and not only for @internalsref{TextScript}s objects.
263 @lilypond[quote,verbatim]
264 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
267 \override Score.RehearsalMark
268 #'break-visibility = #begin-of-line-invisible
269 \override Score.RehearsalMark #'self-alignment-X = #right
271 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
272 c2^\markup{ don't be \flat }
273 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
275 a2\mark \markup{ \large \bold Fine }
279 \addlyrics { bar, foo \markup{ \italic bar! } }
283 A @code{\markup} block can also be printed on its own at the top-level
284 of the input file, away from
285 any @code{\score} block. This syntax is described in
286 @ref{Multiple scores in a book}.
288 @lilypond[quote,ragged-right,verbatim]
289 \markup{ Here is some text. }
292 @cindex font switching
294 Some font switching commands are demonstrated here. Such commands
295 apply only to the first following word; several words may be affected
296 by enclosing them in braces.
299 \markup @{ \bold @{ hi there @} @}
302 @c TODO: remove the following line and example? -vv
304 For clarity, you can also do this for single arguments, e.g.,
307 \markup @{ is \italic @{ anyone @} home @}
310 The markup mode can be used to compose expressions, similar to
311 mathematical expressions, XML documents, and music expressions.
312 Such expressions can be vertically stacked, horizontally centered,
313 or aligned in different ways:
315 @lilypond[quote,verbatim,fragment,relative=1]
316 c1^\markup { \column { a bbbb \line { c d } } }
317 c1^\markup { \center-align { a bbbb c } }
318 c1^\markup { \line { a b c } }
321 Lists with no previous command are not kept distinct. In
322 the following example, the two @code{\markup} expressions
325 @c TODO: merge these two examples in a @lilypond example -vv
328 \center-align @{ @{ a b @} @{ c d @} @}
329 \center-align @{ a b c d @}
334 To keep lists of words distinct, please use quotes @code{"} or
335 the @code{\line} command
337 @lilypond[quote,verbatim,fragment,relative=1]
339 c4^\markup{ \center-align { on three lines } }
340 c4^\markup{ \center-align { "all one line" } }
341 c4^\markup{ \center-align { { on three lines } } }
342 c4^\markup{ \center-align { \line { on one line } } }
345 Markups can be stored in variables and these variables may be
346 attached to notes, like
349 allegro = \markup @{ \bold \large @{ Allegro @} @}
350 @{ a^\allegro b c d @}
353 Some objects have alignment procedures of their own, which cancel
354 out any effects of alignments applied to their markup arguments as
355 a whole. For example, the @internalsref{RehearsalMark} is
356 horizontally centered, so using @code{\mark \markup @{ \left-align
357 .. @}} has no effect.
359 In addition, vertical placement is performed after creating the
360 text markup object. If you wish to move an entire piece of
361 markup, you need to use the #'padding property or create an
362 @q{anchor} point inside the markup (generally with @code{\hspace
365 @lilypond[quote,verbatim,fragment,relative=1]
367 c'4^\markup{ \raise #5 "not raised" }
368 \once \override TextScript #'padding = #3
369 c'4^\markup{ raised }
370 c'4^\markup{ \hspace #0 \raise #1.5 raised }
373 Some situations (such as dynamic marks) have preset font-related
374 properties. If you are creating text in such situations, it is
375 advisable to cancel those properties with @code{normal-text}. See
376 @ref{Text markup commands}, for more details.
381 This manual: @ref{Text markup commands}.
383 Snippets: @lsrdir{Text,Text}
385 Internals Reference: @internalsref{TextScript}.
387 Init files: @file{scm/@/new@/-markup@/.scm}.
392 Kerning or generation of ligatures is only done when the @TeX{}
393 backend is used. In this case, LilyPond does not account for them
394 so texts will be spaced slightly too wide.
396 Syntax errors for markup mode are confusing.
400 @subsubsection Nested scores
402 It is possible to nest music inside markups, by adding a
403 @code{\score} block to a markup expression. Such a score must
404 contain a @code{\layout} block.
406 @lilypond[quote,verbatim,ragged-right]
410 \relative { c4 d e f }
420 Snippets: @lsrdir{Text,Text}
422 @node Page wrapping text
423 @subsubsection Page wrapping text
425 Whereas @code{\markup} is used to enter a non-breakable block of
426 text, @code{\markuplines} can be used at top-level to enter lines
427 of text that can spread over multiple pages:
432 A very long text of justified lines.
436 An other very long paragraph.
443 @code{\markuplines} accepts a list of markup, that is either the
444 result of a markup list command, or a list of markups or of markup
445 lists. The built-in markup list commands are described in
446 @ref{Text markup list commands}.
450 This manual: @ref{Text markup list commands}, @ref{New
451 markup list command definition}.
453 Snippets: @lsrdir{Text,Text}
457 @funindex \markuplines
461 @subsubsection Font selection
463 @cindex font selection
464 @cindex font magnification
465 @funindex font-interface
467 By setting the object properties described below, you can select a
468 font from the preconfigured font families. LilyPond has default
469 support for the feta music fonts. Text fonts are selected through
470 Pango/FontConfig. The serif font defaults to New Century
471 Schoolbook, the sans and typewriter to whatever the Pango
472 installation defaults to.
476 @item @code{font-encoding}
477 is a symbol that sets layout of the glyphs. This should only be
478 set to select different types of non-text fonts, e.g.
480 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
481 standard music font, including ancient glyphs, @code{fetaDynamic}
482 for dynamic signs and @code{fetaNumber} for the number font.
484 @item @code{font-family}
485 is a symbol indicating the general class of the typeface.
486 Supported are @code{roman} (Computer Modern), @code{sans}, and
489 @item @code{font-shape}
490 is a symbol indicating the shape of the font. There are typically
491 several font shapes available for each font family. Choices are
492 @code{italic}, @code{caps}, and @code{upright}.
494 @item @code{font-series}
495 is a symbol indicating the series of the font. There are
496 typically several font series for each font family and shape.
497 Choices are @code{medium} and @code{bold}.
501 Fonts selected in the way sketched above come from a predefined
502 style sheet. If you want to use a font from outside the style
503 sheet, then set the @code{font-name} property,
505 @lilypond[fragment,verbatim]
507 \override Staff.TimeSignature #'font-name = #"Charter"
508 \override Staff.TimeSignature #'font-size = #2
511 \override #'(font-name . "Vera Bold")
512 { This text is in Vera Bold }
518 Any font can be used, as long as it is available to
519 Pango/FontConfig. To get a full list of all available fonts, run
523 lilypond -dshow-available-fonts blabla
526 (the last argument of the command can be anything, but has to be
530 The size of the font may be set with the @code{font-size}
531 property. The resulting size is taken relative to the
532 @code{text-font-size} as defined in the @code{\paper} block.
535 @cindex font magnification
538 It is also possible to change the default font family for the
539 entire document. This is done by calling the
540 @code{make-pango-font-tree} from within the @code{\paper} block.
541 The function takes names for the font families to use for roman,
542 sans serif and monospaced text. For example,
544 @cindex font families, setting
553 (make-pango-font-tree "Times New Roman"
560 c'^\markup { roman: foo \sans bla \typewriter bar }
564 @c we don't do Helvetica / Courier, since GS incorrectly loads
571 Snippets: @lsrdir{Text,Text}