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.
14 @lilypondfile[quote]{text-headword.ly}
16 This section explains how to include text (with various
17 formatting) in your scores.
20 Some text elements that are not dealt with here are discussed in other
21 specific sections: @ref{Vocal music}, @ref{Titles and headers}.
24 @cindex Text, other languages
25 @warning{To write accented and special text (such as characters
26 from other languages), simply insert the characters directly into
27 the LilyPond file. The file must be saved as UTF-8. For more
28 information, see @ref{Text encoding}.}
37 @subsection Writing text
48 @subsubsection Text scripts
51 @cindex text items, non-empty
52 @cindex non-empty texts
54 It is possible to add arbitrary text indications
55 to a score, as demonstrated in the following example.
56 Such indications can also be manually placed
57 above or below the staff, using the
58 simple syntax described in @ref{Controlling direction and
61 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
62 d8^"pizz." e f g a4-"scherz." f
65 In LilyPond, such text strings are called @command{markup}
66 objects. This syntax is actually a shorthand; more complex text
67 formatting may be added to a note by explicitly using a
68 @code{\markup} block, as described in @ref{Formatting text}.
70 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
71 d8^\markup { \italic pizz. } e f g
72 a4_\markup { \tiny scherz. \bold molto } f
75 By default, text indications do not influence the note spacing.
76 However, their widths can be taken into account:
77 in the following example, the first text string does not affect
78 spacing, whereas the second one does.
80 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
81 d8^"pizz." e f g \textLengthOn a4_"scherzando" f
86 @funindex \textLengthOn
88 @funindex \textLengthOff
94 Notation Reference: @ref{Formatting text},
95 @ref{Controlling direction and placement}.
97 Snippets: @lsrdir{Text,Text}
99 Internals Reference: @internalsref{TextScript}.
103 Checking to make sure that text scripts and lyrics are within the
104 margins is a relatively large computational task. To speed up
105 processing, LilyPond does not perform such calculations by
106 default; to enable it, use
109 \override Score.PaperColumn #'keep-inside-line = ##t
114 @subsubsection Text spanners
116 @cindex Text spanners
118 Some performance indications, e.g., @i{rallentando} or
119 @i{accelerando}, are written as text and are extended over many
120 measures with dotted lines.
122 Such objects, called @q{spanners}, may be created
123 from one note to another by using the following syntax:
125 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
126 \override TextSpanner #'bound-details #'left #'text = "rit."
132 The string to be printed is set through
133 object properties. By default it is printed in italic characters,
134 but different formatting can be obtained using
135 @code{\markup} blocks:
137 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
138 \override TextSpanner #'bound-details #'left #'text =
139 \markup { \upright "rit." }
144 The line style, as well as the text string, can be defined as an
145 object property. This syntax is described in @ref{Line styles}.
149 @funindex textSpannerUp
150 @code{\textSpannerUp},
151 @funindex textSpannerDown
152 @code{\textSpannerDown},
153 @funindex textSpannerNeutral
154 @code{\textSpannerNeutral}
158 Notation Reference: @ref{Line styles}.
160 Snippets: @lsrdir{Text,Text}
162 Internals Reference: @internalsref{TextSpanner}.
166 @subsubsection Text marks
168 @cindex coda on bar line
169 @cindex segno on bar line
170 @cindex fermata on bar line
171 @cindex bar lines, symbols on
174 Various text elements can be added to a score using
175 the syntax described in @ref{Rehearsal marks}:
177 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
178 c4\mark "dolce" c c c
181 This syntax makes possible to put any text on a bar line;
182 more complex text formatting may be added using a @code{\markup}
183 block, as described in @ref{Formatting text}. This can be used to print
184 signs like coda, segno or fermata, by specifying the appropriate
187 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
188 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
193 Such objects are only typeset above the top staff of the score; they
194 can be placed above the bar line or between notes, depending on whether
195 you specify it at the end or the middle of a bar. When specified at the
196 beginning of a score or at a line break, the mark will be printed at
197 the beginning of the line (the next line, in case of a line break).
199 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
201 c\mark "assai" \break
208 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
209 {printing-marks-at-the-end-of-a-line-or-a-score.ly}
211 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
212 {aligning-marks-with-various-notation-objects.ly}
214 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
215 {printing-marks-on-every-staff.ly}
219 Notation Reference: @ref{Rehearsal marks},
220 @ref{Formatting text}, @ref{The Feta font}.
222 Snippets: @lsrdir{Text,Text}
224 Internals Reference: @internalsref{RehearsalMark}.
227 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
228 @c delete this sentence. -gp
229 @c A workaround is suggested in the first @snippets item -vv
231 If a mark is entered at the end of the last bar of the score (where
232 there is no next line), then the mark will not be printed at
236 @subsubsection Separate text
238 @cindex separate text
239 @cindex standalone text
240 @cindex top-level text
241 @cindex text, standalone
244 A @code{\markup} block can exist by itself, outside of any
245 any @code{\score} block. This syntax is called a @q{top-level
246 expression}, and is described in @code{File structure}.
248 @c TODO: turn this into a @lilypond example
257 This allows to print text separately
258 from the music, which is particularly
259 useful when the input file contains
260 several music pieces, as described in
261 @ref{Multiple scores in a book}.
275 Using a specific syntax, text blocks can be spread
276 over multiple pages, making possible to print
277 text documents or books -- and therefore to
278 use LilyPond as a word processor. This syntax is described in
279 @ref{Page wrapping text}.
284 TODO: add convenient snippets, e.g.
285 "Inserting large plain text sections"
286 (this requires the LSR to be updated) -vv
291 Notation Reference: @code{Formatting text},
292 @code{File structure},
293 @ref{Multiple scores in a book},
294 @ref{Page wrapping text}.
296 Snippets: @lsrdir{Text,Text}.
298 Internals Reference: @internalsref{TextScript}.
304 @funindex \markuplines
308 @node Formatting text
309 @subsection Formatting text
312 * Text markup introduction::
314 * Page wrapping text::
318 @node Text markup introduction
319 @subsubsection Text markup introduction
326 A @code{\markup} block is used to typeset text with an extensible syntax,
327 called @q{markup mode}.
328 Specific commands can be entered in this mode, using the
329 backslash @code{\} character.
330 @c TODO: move the following sentence (and add an example?) -vv
331 To @emph{print} such characters as
332 @code{\} and @code{#} in the output, use double
335 @lilypond[quote,verbatim,fragment,relative=1]
337 c1_\markup { hi there }
338 c1^\markup { hi \bold there, is \italic {anyone home?} }
339 c1_\markup { "\special {weird} #characters" }
343 An exhaustive list of @code{\markup}-specific commands can be found in
344 @ref{Text markup commands}.
346 @code{\markup} blocks can be used anywhere text is called,
347 and not only for @internalsref{TextScript}s objects.
349 @lilypond[quote,verbatim]
350 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
353 \override Score.RehearsalMark
354 #'break-visibility = #begin-of-line-invisible
355 \override Score.RehearsalMark #'self-alignment-X = #right
357 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
358 c2^\markup{ don't be \flat }
359 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
361 a2\mark \markup{ \large \bold Fine }
365 \addlyrics { bar, foo \markup{ \italic bar! } }
369 A @code{\markup} block can also be printed on its own at the top-level
370 of the input file, away from
371 any @code{\score} block. This syntax is described in
372 @ref{Multiple scores in a book}.
374 @lilypond[quote,ragged-right,verbatim]
375 \markup{ Here is some text. }
378 @cindex font switching
380 Some font switching commands are demonstrated here. Such commands
381 apply only to the first following word; several words may be affected
382 by enclosing them in braces.
385 \markup @{ \bold @{ hi there @} @}
388 @c TODO: remove the following line and example? -vv
390 For clarity, you can also do this for single arguments, e.g.,
393 \markup @{ is \italic @{ anyone @} home @}
396 The markup mode can be used to compose expressions, similar to
397 mathematical expressions, XML documents, and music expressions.
398 Such expressions can be vertically stacked, horizontally centered,
399 or aligned in different ways:
401 @lilypond[quote,verbatim,fragment,relative=1]
402 c1^\markup { \column { a bbbb \line { c d } } }
403 c1^\markup { \center-align { a bbbb c } }
404 c1^\markup { \line { a b c } }
407 Lists with no previous command are not kept distinct. In
408 the following example, the two @code{\markup} expressions
411 @c TODO: merge these two examples in a @lilypond example -vv
414 \center-align @{ @{ a b @} @{ c d @} @}
415 \center-align @{ a b c d @}
420 To keep lists of words distinct, please use quotes @code{"} or
421 the @code{\line} command
423 @lilypond[quote,verbatim,fragment,relative=1]
425 c4^\markup{ \center-align { on three lines } }
426 c4^\markup{ \center-align { "all one line" } }
427 c4^\markup{ \center-align { { on three lines } } }
428 c4^\markup{ \center-align { \line { on one line } } }
431 Markups can be stored in variables and these variables may be
432 attached to notes, like
435 allegro = \markup @{ \bold \large @{ Allegro @} @}
436 @{ a^\allegro b c d @}
439 Some objects have alignment procedures of their own, which cancel
440 out any effects of alignments applied to their markup arguments as
441 a whole. For example, the @internalsref{RehearsalMark} is
442 horizontally centered, so using @code{\mark \markup @{ \left-align
443 .. @}} has no effect.
445 In addition, vertical placement is performed after creating the
446 text markup object. If you wish to move an entire piece of
447 markup, you need to use the #'padding property or create an
448 @q{anchor} point inside the markup (generally with @code{\hspace
451 @lilypond[quote,verbatim,fragment,relative=1]
453 c'4^\markup{ \raise #5 "not raised" }
454 \once \override TextScript #'padding = #3
455 c'4^\markup{ raised }
456 c'4^\markup{ \hspace #0 \raise #1.5 raised }
459 Some situations (such as dynamic marks) have preset font-related
460 properties. If you are creating text in such situations, it is
461 advisable to cancel those properties with @code{normal-text}. See
462 @ref{Text markup commands}, for more details.
467 This manual: @ref{Text markup commands}.
469 Snippets: @lsrdir{Text,Text}
471 Internals Reference: @internalsref{TextScript}.
473 Init files: @file{scm/@/new@/-markup@/.scm}.
478 Kerning or generation of ligatures is only done when the @TeX{}
479 backend is used. In this case, LilyPond does not account for them
480 so texts will be spaced slightly too wide.
482 Syntax errors for markup mode are confusing.
486 @subsubsection Nested scores
488 It is possible to nest music inside markups, by adding a
489 @code{\score} block to a markup expression. Such a score must
490 contain a @code{\layout} block.
492 @lilypond[quote,verbatim,ragged-right]
496 \relative { c4 d e f }
506 Snippets: @lsrdir{Text,Text}
508 @node Page wrapping text
509 @subsubsection Page wrapping text
511 Whereas @code{\markup} is used to enter a non-breakable block of
512 text, @code{\markuplines} can be used at top-level to enter lines
513 of text that can spread over multiple pages:
518 A very long text of justified lines.
522 An other very long paragraph.
529 @code{\markuplines} accepts a list of markup, that is either the
530 result of a markup list command, or a list of markups or of markup
531 lists. The built-in markup list commands are described in
532 @ref{Text markup list commands}.
536 This manual: @ref{Text markup list commands}, @ref{New
537 markup list command definition}.
539 Snippets: @lsrdir{Text,Text}
543 @funindex \markuplines
547 @subsubsection Font selection
549 @cindex font selection
550 @cindex font magnification
551 @funindex font-interface
553 By setting the object properties described below, you can select a
554 font from the preconfigured font families. LilyPond has default
555 support for the feta music fonts. Text fonts are selected through
556 Pango/FontConfig. The serif font defaults to New Century
557 Schoolbook, the sans and typewriter to whatever the Pango
558 installation defaults to.
562 @item @code{font-encoding}
563 is a symbol that sets layout of the glyphs. This should only be
564 set to select different types of non-text fonts, e.g.
566 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
567 standard music font, including ancient glyphs, @code{fetaDynamic}
568 for dynamic signs and @code{fetaNumber} for the number font.
570 @item @code{font-family}
571 is a symbol indicating the general class of the typeface.
572 Supported are @code{roman} (Computer Modern), @code{sans}, and
575 @item @code{font-shape}
576 is a symbol indicating the shape of the font. There are typically
577 several font shapes available for each font family. Choices are
578 @code{italic}, @code{caps}, and @code{upright}.
580 @item @code{font-series}
581 is a symbol indicating the series of the font. There are
582 typically several font series for each font family and shape.
583 Choices are @code{medium} and @code{bold}.
587 Fonts selected in the way sketched above come from a predefined
588 style sheet. If you want to use a font from outside the style
589 sheet, then set the @code{font-name} property,
591 @lilypond[fragment,verbatim]
593 \override Staff.TimeSignature #'font-name = #"Charter"
594 \override Staff.TimeSignature #'font-size = #2
597 \override #'(font-name . "Vera Bold")
598 { This text is in Vera Bold }
604 Any font can be used, as long as it is available to
605 Pango/FontConfig. To get a full list of all available fonts, run
609 lilypond -dshow-available-fonts blabla
612 (the last argument of the command can be anything, but has to be
616 The size of the font may be set with the @code{font-size}
617 property. The resulting size is taken relative to the
618 @code{text-font-size} as defined in the @code{\paper} block.
621 @cindex font magnification
624 It is also possible to change the default font family for the
625 entire document. This is done by calling the
626 @code{make-pango-font-tree} from within the @code{\paper} block.
627 The function takes names for the font families to use for roman,
628 sans serif and monospaced text. For example,
630 @cindex font families, setting
639 (make-pango-font-tree "Times New Roman"
646 c'^\markup { roman: foo \sans bla \typewriter bar }
650 @c we don't do Helvetica / Courier, since GS incorrectly loads
657 Snippets: @lsrdir{Text,Text}