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}.}
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
56 to a score, as demonstrated in the following example.
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}, @ref{The Feta font}.
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
258 This allows to print text separately
259 from the music, which is particularly
260 useful when the input file contains
261 several music pieces, as described in
262 @ref{Multiple scores in a book}.
276 Using a specific syntax, text blocks can be spread
277 over multiple pages, making possible to print
278 text documents or books -- and therefore to
279 use LilyPond as a word processor. This syntax is described in
280 @ref{Multi-pages markup}.
285 TODO: add convenient snippets, e.g.
286 "Inserting large plain text sections"
287 (this requires the LSR to be updated) -vv
292 Notation Reference: @code{Formatting text},
293 @code{File structure},
294 @ref{Multiple scores in a book},
295 @ref{Multi-pages markup}.
297 Snippets: @lsrdir{Text,Text}.
299 Internals Reference: @internalsref{TextScript}.
305 @funindex \markuplines
309 @node Formatting text
310 @subsection Formatting text
313 * Text markup introduction::
314 * Common markup commands::
316 * Graphic notation inside markup::
317 * Music notation inside markup::
318 * Multi-pages markup::
321 @node Text markup introduction
322 @subsubsection Text markup introduction
329 A @code{\markup} block is used to typeset text with an extensible syntax,
330 called @q{markup mode}.
331 Specific commands can be entered in this mode, using the
332 backslash @code{\} character.
333 @c TODO: move the following sentence (and add an example?) -vv
334 To @emph{print} such characters as
335 @code{\} and @code{#} in the output, use double
338 @lilypond[quote,verbatim,fragment,relative=1]
340 c1_\markup { hi there }
341 c1^\markup { hi \bold there, is \italic {anyone home?} }
342 c1_\markup { "\special {weird} #characters" }
346 An exhaustive list of @code{\markup}-specific commands can be found in
347 @ref{Text markup commands}.
349 @code{\markup} blocks can be used anywhere text is called,
350 and not only for @internalsref{TextScript}s objects.
352 @lilypond[quote,verbatim]
353 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
356 \override Score.RehearsalMark
357 #'break-visibility = #begin-of-line-invisible
358 \override Score.RehearsalMark #'self-alignment-X = #right
360 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
361 c2^\markup{ don't be \flat }
362 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
364 a2\mark \markup{ \large \bold Fine }
368 \addlyrics { bar, foo \markup{ \italic bar! } }
372 A @code{\markup} block can also be printed on its own at the top-level
373 of the input file, away from
374 any @code{\score} block. This syntax is described in
375 @ref{Multiple scores in a book}.
377 @lilypond[quote,ragged-right,verbatim]
378 \markup{ Here is some text. }
381 @cindex font switching
383 Some font switching commands are demonstrated here. Such commands
384 apply only to the first following word; several words may be affected
385 by enclosing them in braces.
388 \markup @{ \bold @{ hi there @} @}
391 @c TODO: remove the following line and example? -vv
393 For clarity, you can also do this for single arguments, e.g.,
396 \markup @{ is \italic @{ anyone @} home @}
399 The markup mode can be used to compose expressions, similar to
400 mathematical expressions, XML documents, and music expressions.
401 Such expressions can be vertically stacked, horizontally centered,
402 or aligned in different ways:
404 @lilypond[quote,verbatim,fragment,relative=1]
405 c1^\markup { \column { a bbbb \line { c d } } }
406 c1^\markup { \center-align { a bbbb c } }
407 c1^\markup { \line { a b c } }
410 Lists with no previous command are not kept distinct. In
411 the following example, the two @code{\markup} expressions
414 @c TODO: merge these two examples in a @lilypond example -vv
417 \center-align @{ @{ a b @} @{ c d @} @}
418 \center-align @{ a b c d @}
423 To keep lists of words distinct, please use quotes @code{"} or
424 the @code{\line} command
426 @lilypond[quote,verbatim,fragment,relative=1]
428 c4^\markup{ \center-align { on three lines } }
429 c4^\markup{ \center-align { "all one line" } }
430 c4^\markup{ \center-align { { on three lines } } }
431 c4^\markup{ \center-align { \line { on one line } } }
434 Markups can be stored in variables and these variables may be
435 attached to notes, like
438 allegro = \markup @{ \bold \large @{ Allegro @} @}
439 @{ a^\allegro b c d @}
442 Some objects have alignment procedures of their own, which cancel
443 out any effects of alignments applied to their markup arguments as
444 a whole. For example, the @internalsref{RehearsalMark} is
445 horizontally centered, so using @code{\mark \markup @{ \left-align
446 .. @}} has no effect.
448 In addition, vertical placement is performed after creating the
449 text markup object. If you wish to move an entire piece of
450 markup, you need to use the #'padding property or create an
451 @q{anchor} point inside the markup (generally with @code{\hspace
454 @lilypond[quote,verbatim,fragment,relative=1]
456 c'4^\markup{ \raise #5 "not raised" }
457 \once \override TextScript #'padding = #3
458 c'4^\markup{ raised }
459 c'4^\markup{ \hspace #0 \raise #1.5 raised }
462 Some situations (such as dynamic marks) have preset font-related
463 properties. If you are creating text in such situations, it is
464 advisable to cancel those properties with @code{normal-text}. See
465 @ref{Text markup commands}, for more details.
470 This manual: @ref{Text markup commands}.
472 Snippets: @lsrdir{Text,Text}
474 Internals Reference: @internalsref{TextScript}.
476 Init files: @file{scm/@/new@/-markup@/.scm}.
481 Kerning or generation of ligatures is only done when the @TeX{}
482 backend is used. In this case, LilyPond does not account for them
483 so texts will be spaced slightly too wide.
485 Syntax errors for markup mode are confusing.
487 @node Common markup commands
488 @subsubsection Common markup commands
493 @subsubsection Text alignment
497 @node Graphic notation inside markup
498 @subsubsection Graphic notation inside markup
502 @node Music notation inside markup
503 @subsubsection Music notation inside markup
505 It is possible to nest music inside markups, by adding a
506 @code{\score} block to a markup expression. Such a score must
507 contain a @code{\layout} block.
509 @lilypond[quote,verbatim,ragged-right]
513 \relative { c4 d e f }
523 Snippets: @lsrdir{Text,Text}
525 @node Multi-pages markup
526 @subsubsection Multi-pages markup
528 Whereas @code{\markup} is used to enter a non-breakable block of
529 text, @code{\markuplines} can be used at top-level to enter lines
530 of text that can spread over multiple pages:
535 A very long text of justified lines.
539 An other very long paragraph.
546 @code{\markuplines} accepts a list of markup, that is either the
547 result of a markup list command, or a list of markups or of markup
548 lists. The built-in markup list commands are described in
549 @ref{Text markup list commands}.
553 This manual: @ref{Text markup list commands}, @ref{New
554 markup list command definition}.
556 Snippets: @lsrdir{Text,Text}
560 @funindex \markuplines
565 @c TODO: move the following subsubsec into NR3 -vv
571 * Entire document fonts::
572 * Single entry fonts::
575 @node Entire document fonts
576 @subsubsection Entire document fonts
578 It is also possible to change the default font family for the
579 entire document. This is done by calling the
580 @code{make-pango-font-tree} from within the @code{\paper} block.
581 The function takes names for the font families to use for roman,
582 sans serif and monospaced text. For example,
584 @cindex font families, setting
593 (make-pango-font-tree "Times New Roman"
600 c'^\markup { roman: foo \sans bla \typewriter bar }
604 @c we don't do Helvetica / Courier, since GS incorrectly loads
608 @node Single entry fonts
609 @subsubsection Single entry fonts
611 @cindex font selection
612 @cindex font magnification
613 @funindex font-interface
615 By setting the object properties described below, you can select a
616 font from the preconfigured font families. LilyPond has default
617 support for the feta music fonts. Text fonts are selected through
618 Pango/FontConfig. The serif font defaults to New Century
619 Schoolbook, the sans and typewriter to whatever the Pango
620 installation defaults to.
624 @item @code{font-encoding}
625 is a symbol that sets layout of the glyphs. This should only be
626 set to select different types of non-text fonts, e.g.
628 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
629 standard music font, including ancient glyphs, @code{fetaDynamic}
630 for dynamic signs and @code{fetaNumber} for the number font.
632 @item @code{font-family}
633 is a symbol indicating the general class of the typeface.
634 Supported are @code{roman} (Computer Modern), @code{sans}, and
637 @item @code{font-shape}
638 is a symbol indicating the shape of the font. There are typically
639 several font shapes available for each font family. Choices are
640 @code{italic}, @code{caps}, and @code{upright}.
642 @item @code{font-series}
643 is a symbol indicating the series of the font. There are
644 typically several font series for each font family and shape.
645 Choices are @code{medium} and @code{bold}.
649 Fonts selected in the way sketched above come from a predefined
650 style sheet. If you want to use a font from outside the style
651 sheet, then set the @code{font-name} property,
653 @lilypond[fragment,verbatim]
655 \override Staff.TimeSignature #'font-name = #"Charter"
656 \override Staff.TimeSignature #'font-size = #2
659 \override #'(font-name . "Vera Bold")
660 { This text is in Vera Bold }
666 Any font can be used, as long as it is available to
667 Pango/FontConfig. To get a full list of all available fonts, run
671 lilypond -dshow-available-fonts blabla
674 (the last argument of the command can be anything, but has to be
678 The size of the font may be set with the @code{font-size}
679 property. The resulting size is taken relative to the
680 @code{text-font-size} as defined in the @code{\paper} block.
683 @cindex font magnification
690 Snippets: @lsrdir{Text,Text}