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 music 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
40 This section introduces different ways of adding text to a score.
51 @subsubsection Text scripts
54 @cindex text items, non-empty
55 @cindex non-empty texts
57 It is possible to add arbitrary text indications
58 to a score, as demonstrated in the following example.
59 Such indications can also be manually placed
60 above or below the staff, using the
61 simple syntax described in @ref{Controlling direction and
64 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
65 d8^"pizz." e f g a4-"scherz." f
68 In LilyPond, such text strings are called @command{markup}
69 objects. This syntax is actually a shorthand; more complex text
70 formatting may be added to a note by explicitly using a
71 @code{\markup} block, as described in @ref{Formatting text}.
73 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
74 d8^\markup { \italic pizz. } e f g
75 a4_\markup { \tiny scherz. \bold molto } f
78 By default, text indications do not influence the note spacing.
79 However, their widths can be taken into account:
80 in the following example, the first text string does not affect
81 spacing, whereas the second one does.
83 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
84 d8^"pizz." e f g \textLengthOn a4_"scherzando" f
89 @funindex \textLengthOn
91 @funindex \textLengthOff
97 Notation Reference: @ref{Formatting text},
98 @ref{Controlling direction and placement}.
100 Snippets: @lsrdir{Text,Text}
102 Internals Reference: @internalsref{TextScript}.
106 Checking to make sure that text scripts and lyrics are within the
107 margins is a relatively large computational task. To speed up
108 processing, LilyPond does not perform such calculations by
109 default; to enable it, use
112 \override Score.PaperColumn #'keep-inside-line = ##t
117 @subsubsection Text spanners
119 @cindex Text spanners
121 Some performance indications, e.g., @i{rallentando} or
122 @i{accelerando}, are written as text and are extended over many
123 measures with dotted lines.
125 Such objects, called @q{spanners}, may be created
126 from one note to another by using the following syntax:
128 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
129 \override TextSpanner #'bound-details #'left #'text = "rit."
135 The string to be printed is set through
136 object properties. By default it is printed in italic characters,
137 but different formatting can be obtained using
138 @code{\markup} blocks:
140 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
141 \override TextSpanner #'bound-details #'left #'text =
142 \markup { \upright "rit." }
147 The line style, as well as the text string, can be defined as an
148 object property. This syntax is described in @ref{Line styles}.
152 @funindex textSpannerUp
153 @code{\textSpannerUp},
154 @funindex textSpannerDown
155 @code{\textSpannerDown},
156 @funindex textSpannerNeutral
157 @code{\textSpannerNeutral}
161 Notation Reference: @ref{Line styles}.
163 Snippets: @lsrdir{Text,Text}
165 Internals Reference: @internalsref{TextSpanner}.
169 @subsubsection Text marks
171 @cindex coda on bar line
172 @cindex segno on bar line
173 @cindex fermata on bar line
174 @cindex bar lines, symbols on
177 Various text elements can be added to a score using
178 the syntax described in @ref{Rehearsal marks}:
180 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
181 c4\mark "dolce" c c c
184 This syntax makes possible to put any text on a bar line;
185 more complex text formatting may be added using a @code{\markup}
186 block, as described in @ref{Formatting text}. This can be used to print
187 signs like coda, segno or fermata, by specifying the appropriate
190 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
191 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
196 Such objects are only typeset above the top staff of the score; they
197 can be placed above the bar line or between notes, depending on whether
198 you specify it at the end or the middle of a bar. When specified at the
199 beginning of a score or at a line break, the mark will be printed at
200 the beginning of the line (the next line, in case of a line break).
202 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
204 c\mark "assai" \break
211 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
212 {printing-marks-at-the-end-of-a-line-or-a-score.ly}
214 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
215 {aligning-marks-with-various-notation-objects.ly}
217 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
218 {printing-marks-on-every-staff.ly}
222 Notation Reference: @ref{Rehearsal marks},
223 @ref{Formatting text}, @ref{The Feta font}.
225 Snippets: @lsrdir{Text,Text}
227 Internals Reference: @internalsref{RehearsalMark}.
230 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
231 @c delete this sentence. -gp
232 @c A workaround is suggested in the first @snippets item -vv
234 If a mark is entered at the end of the last bar of the score (where
235 there is no next line), then the mark will not be printed at
239 @subsubsection Separate text
241 @cindex separate text
242 @cindex standalone text
243 @cindex top-level text
244 @cindex text, standalone
247 A @code{\markup} block can exist by itself, outside of any
248 any @code{\score} block. This syntax is called a @q{top-level
249 expression}, and is described in @code{File structure}.
251 @c TODO: turn this into a @lilypond example
260 This allows to print text separately
261 from the music, which is particularly
262 useful when the input file contains
263 several music pieces, as described in
264 @ref{Multiple scores in a book}.
278 Using a specific syntax, text blocks can be spread
279 over multiple pages, making possible to print
280 text documents or books -- and therefore to
281 use LilyPond as a word processor. This syntax is described in
282 @ref{Multi-pages markup}.
287 TODO: add convenient snippets, e.g.
288 "Inserting large plain text sections"
289 (this requires the LSR to be updated) -vv
294 Notation Reference: @code{Formatting text},
295 @code{File structure},
296 @ref{Multiple scores in a book},
297 @ref{Multi-pages markup}.
299 Snippets: @lsrdir{Text,Text}.
301 Internals Reference: @internalsref{TextScript}.
307 @funindex \markuplines
311 @node Formatting text
312 @subsection Formatting text
314 This section presents basic and advanced text formatting,
315 using the @code{\markup} mode specific syntax.
318 * Text markup introduction::
319 * Common markup commands::
321 * Graphic notation inside markup::
322 * Music notation inside markup::
323 * Multi-pages markup::
326 @node Text markup introduction
327 @subsubsection Text markup introduction
334 A @code{\markup} block is used to typeset text with an extensible syntax,
335 called @q{markup mode}.
336 Specific commands can be entered in this mode, using the
337 backslash @code{\} character.
338 @c TODO: move the following sentence (and add an example?) -vv
339 To @emph{print} such characters as
340 @code{\} and @code{#} in the output, use double
343 @lilypond[quote,verbatim,fragment,relative=1]
345 c1_\markup { hi there }
346 c1^\markup { hi \bold there, is \italic {anyone home?} }
347 c1_\markup { "\special {weird} #characters" }
351 An exhaustive list of @code{\markup}-specific commands can be found in
352 @ref{Text markup commands}.
354 @code{\markup} blocks can be used anywhere text is called,
355 and not only for @internalsref{TextScript}s objects.
357 @lilypond[quote,verbatim]
358 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
361 \override Score.RehearsalMark
362 #'break-visibility = #begin-of-line-invisible
363 \override Score.RehearsalMark #'self-alignment-X = #right
365 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
366 c2^\markup{ don't be \flat }
367 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
369 a2\mark \markup{ \large \bold Fine }
373 \addlyrics { bar, foo \markup{ \italic bar! } }
377 A @code{\markup} block can also be printed on its own at the top-level
378 of the input file, away from
379 any @code{\score} block. This syntax is described in
380 @ref{Multiple scores in a book}.
382 @lilypond[quote,ragged-right,verbatim]
383 \markup{ Here is some text. }
386 @cindex font switching
388 Some font switching commands are demonstrated here. Such commands
389 apply only to the first following word; several words may be affected
390 by enclosing them in braces.
393 \markup @{ \bold @{ hi there @} @}
396 @c TODO: remove the following line and example? -vv
398 For clarity, you can also do this for single arguments, e.g.,
401 \markup @{ is \italic @{ anyone @} home @}
404 The markup mode can be used to compose expressions, similar to
405 mathematical expressions, XML documents, and music expressions.
406 Such expressions can be vertically stacked, horizontally centered,
407 or aligned in different ways:
409 @lilypond[quote,verbatim,fragment,relative=1]
410 c1^\markup { \column { a bbbb \line { c d } } }
411 c1^\markup { \center-align { a bbbb c } }
412 c1^\markup { \line { a b c } }
415 Lists with no previous command are not kept distinct. In
416 the following example, the two @code{\markup} expressions
419 @c TODO: merge these two examples in a @lilypond example -vv
422 \center-align @{ @{ a b @} @{ c d @} @}
423 \center-align @{ a b c d @}
428 To keep lists of words distinct, please use quotes @code{"} or
429 the @code{\line} command
431 @lilypond[quote,verbatim,fragment,relative=1]
433 c4^\markup{ \center-align { on three lines } }
434 c4^\markup{ \center-align { "all one line" } }
435 c4^\markup{ \center-align { { on three lines } } }
436 c4^\markup{ \center-align { \line { on one line } } }
439 Markups can be stored in variables and these variables may be
440 attached to notes, like
443 allegro = \markup @{ \bold \large @{ Allegro @} @}
444 @{ a^\allegro b c d @}
447 Some objects have alignment procedures of their own, which cancel
448 out any effects of alignments applied to their markup arguments as
449 a whole. For example, the @internalsref{RehearsalMark} is
450 horizontally centered, so using @code{\mark \markup @{ \left-align
451 .. @}} has no effect.
453 In addition, vertical placement is performed after creating the
454 text markup object. If you wish to move an entire piece of
455 markup, you need to use the #'padding property or create an
456 @q{anchor} point inside the markup (generally with @code{\hspace
459 @lilypond[quote,verbatim,fragment,relative=1]
461 c'4^\markup{ \raise #5 "not raised" }
462 \once \override TextScript #'padding = #3
463 c'4^\markup{ raised }
464 c'4^\markup{ \hspace #0 \raise #1.5 raised }
467 Some situations (such as dynamic marks) have preset font-related
468 properties. If you are creating text in such situations, it is
469 advisable to cancel those properties with @code{normal-text}. See
470 @ref{Text markup commands}, for more details.
475 This manual: @ref{Text markup commands}.
477 Snippets: @lsrdir{Text,Text}
479 Internals Reference: @internalsref{TextScript}.
481 Init files: @file{scm/@/new@/-markup@/.scm}.
486 Kerning or generation of ligatures is only done when the @TeX{}
487 backend is used. In this case, LilyPond does not account for them
488 so texts will be spaced slightly too wide.
490 Syntax errors for markup mode are confusing.
492 @node Common markup commands
493 @subsubsection Common markup commands
498 @subsubsection Text alignment
502 @node Graphic notation inside markup
503 @subsubsection Graphic notation inside markup
507 @node Music notation inside markup
508 @subsubsection Music notation inside markup
510 It is possible to nest music inside markups, by adding a
511 @code{\score} block to a markup expression. Such a score must
512 contain a @code{\layout} block.
514 @lilypond[quote,verbatim,ragged-right]
518 \relative { c4 d e f }
528 Snippets: @lsrdir{Text,Text}
530 @node Multi-pages markup
531 @subsubsection Multi-pages markup
533 Whereas @code{\markup} is used to enter a non-breakable block of
534 text, @code{\markuplines} can be used at top-level to enter lines
535 of text that can spread over multiple pages:
540 A very long text of justified lines.
544 An other very long paragraph.
551 @code{\markuplines} accepts a list of markup, that is either the
552 result of a markup list command, or a list of markups or of markup
553 lists. The built-in markup list commands are described in
554 @ref{Text markup list commands}.
558 This manual: @ref{Text markup list commands}, @ref{New
559 markup list command definition}.
561 Snippets: @lsrdir{Text,Text}
565 @funindex \markuplines
570 @c TODO: move the following subsubsec into NR3 -vv
576 * Entire document fonts::
577 * Single entry fonts::
580 @node Entire document fonts
581 @subsubsection Entire document fonts
583 It is also possible to change the default font family for the
584 entire document. This is done by calling the
585 @code{make-pango-font-tree} from within the @code{\paper} block.
586 The function takes names for the font families to use for roman,
587 sans serif and monospaced text. For example,
589 @cindex font families, setting
598 (make-pango-font-tree "Times New Roman"
605 c'^\markup { roman: foo \sans bla \typewriter bar }
609 @c we don't do Helvetica / Courier, since GS incorrectly loads
613 @node Single entry fonts
614 @subsubsection Single entry fonts
616 @cindex font selection
617 @cindex font magnification
618 @funindex font-interface
620 By setting the object properties described below, you can select a
621 font from the preconfigured font families. LilyPond has default
622 support for the feta music fonts. Text fonts are selected through
623 Pango/FontConfig. The serif font defaults to New Century
624 Schoolbook, the sans and typewriter to whatever the Pango
625 installation defaults to.
629 @item @code{font-encoding}
630 is a symbol that sets layout of the glyphs. This should only be
631 set to select different types of non-text fonts, e.g.
633 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
634 standard music font, including ancient glyphs, @code{fetaDynamic}
635 for dynamic signs and @code{fetaNumber} for the number font.
637 @item @code{font-family}
638 is a symbol indicating the general class of the typeface.
639 Supported are @code{roman} (Computer Modern), @code{sans}, and
642 @item @code{font-shape}
643 is a symbol indicating the shape of the font. There are typically
644 several font shapes available for each font family. Choices are
645 @code{italic}, @code{caps}, and @code{upright}.
647 @item @code{font-series}
648 is a symbol indicating the series of the font. There are
649 typically several font series for each font family and shape.
650 Choices are @code{medium} and @code{bold}.
654 Fonts selected in the way sketched above come from a predefined
655 style sheet. If you want to use a font from outside the style
656 sheet, then set the @code{font-name} property,
658 @lilypond[fragment,verbatim]
660 \override Staff.TimeSignature #'font-name = #"Charter"
661 \override Staff.TimeSignature #'font-size = #2
664 \override #'(font-name . "Vera Bold")
665 { This text is in Vera Bold }
671 Any font can be used, as long as it is available to
672 Pango/FontConfig. To get a full list of all available fonts, run
676 lilypond -dshow-available-fonts blabla
679 (the last argument of the command can be anything, but has to be
683 The size of the font may be set with the @code{font-size}
684 property. The resulting size is taken relative to the
685 @code{text-font-size} as defined in the @code{\paper} block.
688 @cindex font magnification
695 Snippets: @lsrdir{Text,Text}