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.
16 Some text elements that are not dealt with here are discussed in other
20 @item @ref{Vocal music}
21 @item @ref{Titles and headers}
25 @cindex Text, other languages
26 @warning{To write accented and special text (such as characters
27 from other languages), simply insert the characters directly into
28 the LilyPond file. The file must be saved as UTF-8. For more
29 information, see @ref{Text encoding}.}
38 @subsection Writing text
49 @subsubsection Text scripts
52 @cindex text items, non-empty
53 @cindex non-empty texts
55 It is possible to add arbitrary text indications with
56 @var{note}@code{-"}@var{text}@code{"}.
57 Such indications can also be manually placed
58 above or below the staff, using the
59 simple syntax described in @ref{Controlling direction and
62 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
63 d8^"pizz." e f g a4-"scherz." f
66 In LilyPond, such text strings are called @command{markup}
67 objects. This syntax is actually a shorthand; more complex text
68 formatting may be added to a note by explicitly using a
69 @code{\markup} block, as described in @ref{Formatting text}.
71 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
72 d8^\markup { \italic pizz. } e f g
73 a4_\markup { \tiny scherz. \bold molto } f
76 By default, text indications do not influence the note spacing.
77 However, their widths can be taken into account:
78 in the following example, the first text string does not affect
79 spacing, whereas the second one does.
81 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
82 d8^"pizz." e f g \textLengthOn a4_"scherzando" f
87 @funindex \textLengthOn
89 @funindex \textLengthOff
95 Notation Reference: @ref{Formatting text},
96 @ref{Controlling direction and placement}.
98 Snippets: @lsrdir{Text,Text}
100 Internals Reference: @internalsref{TextScript}.
104 Checking to make sure that text scripts and lyrics are within the
105 margins is a relatively large computational task. To speed up
106 processing, LilyPond does not perform such calculations by
107 default; to enable it, use
110 \override Score.PaperColumn #'keep-inside-line = ##t
115 @subsubsection Text spanners
117 @cindex Text spanners
119 Some performance indications, e.g., @i{rallentando} or
120 @i{accelerando}, are written as text and are extended over many
121 measures with dotted lines.
123 Such objects, called @q{spanners}, may be created
124 from one note to another by using the following syntax:
126 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
127 \override TextSpanner #'bound-details #'left #'text = "rit."
133 The string to be printed is set through
134 object properties. By default it is printed in italic characters,
135 but different formatting can be obtained using
136 @code{\markup} blocks:
138 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
139 \override TextSpanner #'bound-details #'left #'text =
140 \markup { \upright "rit." }
145 The line style, as well as the text string, can be defined as an
146 object property. This syntax is described in @ref{Line styles}.
150 @funindex textSpannerUp
151 @code{\textSpannerUp},
152 @funindex textSpannerDown
153 @code{\textSpannerDown},
154 @funindex textSpannerNeutral
155 @code{\textSpannerNeutral}
159 Notation Reference: @ref{Line styles}.
161 Snippets: @lsrdir{Text,Text}
163 Internals Reference: @internalsref{TextSpanner}.
167 @subsubsection Text marks
169 @cindex coda on bar line
170 @cindex segno on bar line
171 @cindex fermata on bar line
172 @cindex bar lines, symbols on
175 Various text elements can be added to a score using
176 the syntax described in @ref{Rehearsal marks}:
178 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
179 c4\mark "dolce" c c c
182 This syntax makes possible to put any text on a bar line;
183 more complex text formatting may be added using a @code{\markup}
184 block, as described in @ref{Formatting text}. This can be used to print
185 signs like coda, segno or fermata, by specifying the appropriate
188 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
189 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
194 Such objects are only typeset above the top staff of the score; they
195 can be placed above the bar line or between notes, depending on whether
196 you specify it at the end or the middle of a bar. When specified at the
197 beginning of a score or at a line break, the mark will be printed at
198 the beginning of the line (the next line, in case of a line break).
200 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
202 c\mark "assai" \break
209 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
210 {printing-marks-at-the-end-of-a-line-or-a-score.ly}
212 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
213 {aligning-marks-with-various-notation-objects.ly}
215 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
216 {printing-marks-on-every-staff.ly}
220 Notation Reference: @ref{Rehearsal marks},
221 @ref{Formatting text}.
223 Snippets: @lsrdir{Text,Text}
225 Internals Reference: @internalsref{RehearsalMark}.
228 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
229 @c delete this sentence. -gp
230 @c A workaround is suggested in the first @snippets item -vv
232 If a mark is entered at the end of the last bar of the score (where
233 there is no next line), then the mark will not be printed at
237 @subsubsection Separate text
239 @cindex separate text
240 @cindex standalone text
241 @cindex top-level text
242 @cindex text, standalone
245 A @code{\markup} block can exist by itself, outside of any
246 any @code{\score} block. This syntax is called a @q{top-level
247 expression}, and is described in @code{File structure}.
249 @c TODO: turn this into a @lilypond example
262 This allows to print text separately
263 from the music, which is particularly
264 useful when the input file contains
265 several music pieces, as described in
266 @ref{Multiple scores in a book}.
280 Using a specific syntax, text blocks can be spread
281 over multiple pages, making possible to print
282 text documents or books -- and therefore to
283 use LilyPond as a word processor. This syntax is described in
284 @ref{Page wrapping text}.
289 TODO: add convenient snippets, e.g.
290 "Inserting large plain text sections"
291 (this requires the LSR to be updated) -vv
296 Notation Reference: @code{Formatting text},
297 @code{File structure},
298 @ref{Multiple scores in a book},
299 @ref{Page wrapping text}.
301 Snippets: @lsrdir{Text,Text}.
303 Internals Reference: @internalsref{TextScript}.
309 @funindex \markuplines
313 @node Formatting text
314 @subsection Formatting text
317 * Text markup introduction::
319 * Page wrapping text::
323 @node Text markup introduction
324 @subsubsection Text markup introduction
331 A @code{\markup} block is used to typeset text with an extensible syntax,
332 called @q{markup mode}.
333 Specific commands can be entered in this mode, using the
334 backslash @code{\} character.
335 @c TODO: move the following sentence (and add an example?) -vv
336 To @emph{print} such characters as
337 @code{\} and @code{#} in the output, use double
340 @lilypond[quote,verbatim,fragment,relative=1]
342 c1_\markup { hi there }
343 c1^\markup { hi \bold there, is \italic {anyone home?} }
344 c1_\markup { "\special {weird} #characters" }
348 An exhaustive list of @code{\markup}-specific commands can be found in
349 @ref{Text markup commands}.
351 @code{\markup} blocks can be used anywhere text is called,
352 and not only for @internalsref{TextScript}s objects.
354 @lilypond[quote,verbatim]
355 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
358 \override Score.RehearsalMark
359 #'break-visibility = #begin-of-line-invisible
360 \override Score.RehearsalMark #'self-alignment-X = #right
362 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
363 c2^\markup{ don't be \flat }
364 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
366 a2\mark \markup{ \large \bold Fine }
370 \addlyrics { bar, foo \markup{ \italic bar! } }
374 A @code{\markup} block can also be printed on its own at the top-level
375 of the input file, away from
376 any @code{\score} block. This syntax is described in
377 @ref{Multiple scores in a book}.
379 @lilypond[quote,ragged-right,verbatim]
380 \markup{ Here is some text. }
383 @cindex font switching
385 Some font switching commands are demonstrated here. Such commands
386 apply only to the first following word; several words may be affected
387 by enclosing them in braces.
390 \markup @{ \bold @{ hi there @} @}
393 @c TODO: remove the following line and example? -vv
395 For clarity, you can also do this for single arguments, e.g.,
398 \markup @{ is \italic @{ anyone @} home @}
401 The markup mode can be used to compose expressions, similar to
402 mathematical expressions, XML documents, and music expressions.
403 Such expressions can be vertically stacked, horizontally centered,
404 or aligned in different ways:
406 @lilypond[quote,verbatim,fragment,relative=1]
407 c1^\markup { \column { a bbbb \line { c d } } }
408 c1^\markup { \center-align { a bbbb c } }
409 c1^\markup { \line { a b c } }
412 Lists with no previous command are not kept distinct. In
413 the following example, the two @code{\markup} expressions
416 @c TODO: merge these two examples in a @lilypond example -vv
419 \center-align @{ @{ a b @} @{ c d @} @}
420 \center-align @{ a b c d @}
425 To keep lists of words distinct, please use quotes @code{"} or
426 the @code{\line} command
428 @lilypond[quote,verbatim,fragment,relative=1]
430 c4^\markup{ \center-align { on three lines } }
431 c4^\markup{ \center-align { "all one line" } }
432 c4^\markup{ \center-align { { on three lines } } }
433 c4^\markup{ \center-align { \line { on one line } } }
436 Markups can be stored in variables and these variables may be
437 attached to notes, like
440 allegro = \markup @{ \bold \large @{ Allegro @} @}
441 @{ a^\allegro b c d @}
444 Some objects have alignment procedures of their own, which cancel
445 out any effects of alignments applied to their markup arguments as
446 a whole. For example, the @internalsref{RehearsalMark} is
447 horizontally centered, so using @code{\mark \markup @{ \left-align
448 .. @}} has no effect.
450 In addition, vertical placement is performed after creating the
451 text markup object. If you wish to move an entire piece of
452 markup, you need to use the #'padding property or create an
453 @q{anchor} point inside the markup (generally with @code{\hspace
456 @lilypond[quote,verbatim,fragment,relative=1]
458 c'4^\markup{ \raise #5 "not raised" }
459 \once \override TextScript #'padding = #3
460 c'4^\markup{ raised }
461 c'4^\markup{ \hspace #0 \raise #1.5 raised }
464 Some situations (such as dynamic marks) have preset font-related
465 properties. If you are creating text in such situations, it is
466 advisable to cancel those properties with @code{normal-text}. See
467 @ref{Text markup commands}, for more details.
472 This manual: @ref{Text markup commands}.
474 Snippets: @lsrdir{Text,Text}
476 Internals Reference: @internalsref{TextScript}.
478 Init files: @file{scm/@/new@/-markup@/.scm}.
483 Kerning or generation of ligatures is only done when the @TeX{}
484 backend is used. In this case, LilyPond does not account for them
485 so texts will be spaced slightly too wide.
487 Syntax errors for markup mode are confusing.
491 @subsubsection Nested scores
493 It is possible to nest music inside markups, by adding a
494 @code{\score} block to a markup expression. Such a score must
495 contain a @code{\layout} block.
497 @lilypond[quote,verbatim,ragged-right]
501 \relative { c4 d e f }
511 Snippets: @lsrdir{Text,Text}
513 @node Page wrapping text
514 @subsubsection Page wrapping text
516 Whereas @code{\markup} is used to enter a non-breakable block of
517 text, @code{\markuplines} can be used at top-level to enter lines
518 of text that can spread over multiple pages:
523 A very long text of justified lines.
527 An other very long paragraph.
534 @code{\markuplines} accepts a list of markup, that is either the
535 result of a markup list command, or a list of markups or of markup
536 lists. The built-in markup list commands are described in
537 @ref{Text markup list commands}.
541 This manual: @ref{Text markup list commands}, @ref{New
542 markup list command definition}.
544 Snippets: @lsrdir{Text,Text}
548 @funindex \markuplines
552 @subsubsection Font selection
554 @cindex font selection
555 @cindex font magnification
556 @funindex font-interface
558 By setting the object properties described below, you can select a
559 font from the preconfigured font families. LilyPond has default
560 support for the feta music fonts. Text fonts are selected through
561 Pango/FontConfig. The serif font defaults to New Century
562 Schoolbook, the sans and typewriter to whatever the Pango
563 installation defaults to.
567 @item @code{font-encoding}
568 is a symbol that sets layout of the glyphs. This should only be
569 set to select different types of non-text fonts, e.g.
571 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
572 standard music font, including ancient glyphs, @code{fetaDynamic}
573 for dynamic signs and @code{fetaNumber} for the number font.
575 @item @code{font-family}
576 is a symbol indicating the general class of the typeface.
577 Supported are @code{roman} (Computer Modern), @code{sans}, and
580 @item @code{font-shape}
581 is a symbol indicating the shape of the font. There are typically
582 several font shapes available for each font family. Choices are
583 @code{italic}, @code{caps}, and @code{upright}.
585 @item @code{font-series}
586 is a symbol indicating the series of the font. There are
587 typically several font series for each font family and shape.
588 Choices are @code{medium} and @code{bold}.
592 Fonts selected in the way sketched above come from a predefined
593 style sheet. If you want to use a font from outside the style
594 sheet, then set the @code{font-name} property,
596 @lilypond[fragment,verbatim]
598 \override Staff.TimeSignature #'font-name = #"Charter"
599 \override Staff.TimeSignature #'font-size = #2
602 \override #'(font-name . "Vera Bold")
603 { This text is in Vera Bold }
609 Any font can be used, as long as it is available to
610 Pango/FontConfig. To get a full list of all available fonts, run
614 lilypond -dshow-available-fonts blabla
617 (the last argument of the command can be anything, but has to be
621 The size of the font may be set with the @code{font-size}
622 property. The resulting size is taken relative to the
623 @code{text-font-size} as defined in the @code{\paper} block.
626 @cindex font magnification
629 It is also possible to change the default font family for the
630 entire document. This is done by calling the
631 @code{make-pango-font-tree} from within the @code{\paper} block.
632 The function takes names for the font families to use for roman,
633 sans serif and monospaced text. For example,
635 @cindex font families, setting
644 (make-pango-font-tree "Times New Roman"
651 c'^\markup { roman: foo \sans bla \typewriter bar }
655 @c we don't do Helvetica / Courier, since GS incorrectly loads
662 Snippets: @lsrdir{Text,Text}