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, as a @qq{top-level
249 expression}. This syntax is described in @ref{File structure}.
251 @lilypond[quote,ragged-right,verbatim]
253 Tomorrow, and tomorrow, and tomorrow...
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}.
264 @lilypond[quote,ragged-right,verbatim]
269 Tomorrow, and tomorrow, and tomorrow...
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-page markup}.
285 TODO: add convenient snippets in input/new -vv
290 Notation Reference: @code{Formatting text},
291 @code{File structure},
292 @ref{Multiple scores in a book},
293 @ref{Multi-page markup}.
295 Snippets: @lsrdir{Text,Text}.
297 Internals Reference: @internalsref{TextScript}.
303 @funindex \markuplines
307 @node Formatting text
308 @subsection Formatting text
310 This section presents basic and advanced text formatting,
311 using the @code{\markup} mode specific syntax.
314 * Text markup introduction::
315 * Common markup commands::
317 * Graphic notation inside markup::
318 * Music notation inside markup::
319 * Multi-page markup::
322 @node Text markup introduction
323 @subsubsection Text markup introduction
330 A @code{\markup} block is used to typeset text with an extensible syntax,
331 called @q{markup mode}.
332 Specific commands can be entered in this mode, using the
333 backslash @code{\} character.
334 @c TODO: move the following sentence (and add an example?) -vv
335 To @emph{print} such characters as
336 @code{\} and @code{#} in the output, use double
339 @lilypond[quote,verbatim,fragment,relative=1]
341 c1_\markup { hi there }
342 c1^\markup { hi \bold there, is \italic {anyone home?} }
343 c1_\markup { "\special {weird} #characters" }
347 An exhaustive list of @code{\markup}-specific commands can be found in
348 @ref{Text markup commands}.
351 @lilypond[quote,verbatim]
352 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
355 \override Score.RehearsalMark
356 #'break-visibility = #begin-of-line-invisible
357 \override Score.RehearsalMark #'self-alignment-X = #right
359 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
360 c2^\markup{ don't be \flat }
361 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
363 a2\mark \markup{ \large \bold Fine }
367 \addlyrics { bar, foo \markup{ \italic bar! } }
373 @cindex font switching
375 Some font switching commands are demonstrated here. Such commands
376 apply only to the first following word; several words may be affected
377 by enclosing them in braces.
380 \markup @{ \bold @{ hi there @} @}
383 @c TODO: remove the following line and example? -vv
385 For clarity, you can also do this for single arguments, e.g.,
388 \markup @{ is \italic @{ anyone @} home @}
391 The markup mode can be used to compose expressions, similar to
392 mathematical expressions, XML documents, and music expressions.
393 Such expressions can be vertically stacked, horizontally centered,
394 or aligned in different ways:
396 @lilypond[quote,verbatim,fragment,relative=1]
397 c1^\markup { \column { a bbbb \line { c d } } }
398 c1^\markup { \center-align { a bbbb c } }
399 c1^\markup { \line { a b c } }
402 Lists with no previous command are not kept distinct. In
403 the following example, the two @code{\markup} expressions
406 @c TODO: merge these two examples in a @lilypond example -vv
409 \center-align @{ @{ a b @} @{ c d @} @}
410 \center-align @{ a b c d @}
415 To keep lists of words distinct, please use quotes @code{"} or
416 the @code{\line} command
418 @lilypond[quote,verbatim,fragment,relative=1]
420 c4^\markup{ \center-align { on three lines } }
421 c4^\markup{ \center-align { "all one line" } }
422 c4^\markup{ \center-align { { on three lines } } }
423 c4^\markup{ \center-align { \line { on one line } } }
426 Markups can be stored in variables and these variables may be
427 attached to notes, like
430 allegro = \markup @{ \bold \large @{ Allegro @} @}
431 @{ a^\allegro b c d @}
434 Some objects have alignment procedures of their own, which cancel
435 out any effects of alignments applied to their markup arguments as
436 a whole. For example, the @internalsref{RehearsalMark} is
437 horizontally centered, so using @code{\mark \markup @{ \left-align
438 .. @}} has no effect.
440 In addition, vertical placement is performed after creating the
441 text markup object. If you wish to move an entire piece of
442 markup, you need to use the #'padding property or create an
443 @q{anchor} point inside the markup (generally with @code{\hspace
446 @lilypond[quote,verbatim,fragment,relative=1]
448 c'4^\markup{ \raise #5 "not raised" }
449 \once \override TextScript #'padding = #3
450 c'4^\markup{ raised }
451 c'4^\markup{ \hspace #0 \raise #1.5 raised }
454 Some situations (such as dynamic marks) have preset font-related
455 properties. If you are creating text in such situations, it is
456 advisable to cancel those properties with @code{normal-text}. See
457 @ref{Text markup commands}, for more details.
460 TODO: here are some commands that could be described here.
461 I'm putting them in bulk, prior to working on this section. -vv
473 \page-ref (see also "Table of contents")
497 This manual: @ref{Text markup commands}.
499 Snippets: @lsrdir{Text,Text}
501 Internals Reference: @internalsref{TextScript}.
503 Init files: @file{scm/@/new@/-markup@/.scm}.
508 Kerning or generation of ligatures is only done when the @TeX{}
509 backend is used. In this case, LilyPond does not account for them
510 so texts will be spaced slightly too wide.
512 Syntax errors for markup mode are confusing.
514 @node Common markup commands
515 @subsubsection Common markup commands
517 Some basic formatting can be used blah blah
526 @c TODO: what's the difference between the following commands? -vv
532 Some alternate font families can easily be selected:
537 \number (only for numbers, such as fingerings and time signatures)
538 @c TODO: add \slashed-digit here? -vv
540 The size can be blah blah blah
544 Some predefined font sizes can be used blah blah
553 Some shorcuts allow to change the font size relatively to its previous value
561 Text may be printed as subscript or superscript:
566 To obtain subscripts or superscripts in a normal text size, use
570 All these settings (except the size) can be reverted to the default font:
576 @subsubsection Text alignment
583 Horizontal alignment:
594 Building a "large" markup:
607 Alignment inside a "large" markup:
617 @node Graphic notation inside markup
618 @subsubsection Graphic notation inside markup
619 Graphics around text:
626 "Standalone" graphics:
646 @node Music notation inside markup
647 @subsubsection Music notation inside markup
649 Notes can be printed in markup mode blah blah:
654 Accidental symbols can be obtained easily:
666 Some other notation objects blah blah
674 @c TODO: add \text here? -vv
676 Any musical symbol can be printed
679 @c TODO: add \lookup here? -vv
682 The markup mode has support for fret diagrams:
686 \fret-diagram-verbose
688 An entire @code{\score} block can even be nested in a @code{\markup}
689 block. In such a case, the @code{\score} must contain a @code{\layout} block.
695 @lilypond[quote,verbatim,ragged-right]
699 \relative { c4 d e f }
709 Snippets: @lsrdir{Text,Text}
711 @node Multi-page markup
712 @subsubsection Multi-page markup
714 Whereas @code{\markup} is used to enter a non-breakable block of
715 text, @code{\markuplines} can be used at top-level to enter lines
716 of text that can spread over multiple pages:
721 A very long text of justified lines.
725 An other very long paragraph.
732 @code{\markuplines} accepts a list of markup, that is either the
733 result of a markup list command, or a list of markups or of markup
734 lists. The built-in markup list commands are described in
735 @ref{Text markup list commands}.
739 This manual: @ref{Text markup list commands}, @ref{New
740 markup list command definition}.
742 Snippets: @lsrdir{Text,Text}
746 @funindex \markuplines
751 @c TODO: move the following subsubsec into NR3 -vv
757 * Entire document fonts::
758 * Single entry fonts::
761 @node Entire document fonts
762 @subsubsection Entire document fonts
764 It is also possible to change the default font family for the
765 entire document. This is done by calling the
766 @code{make-pango-font-tree} from within the @code{\paper} block.
767 The function takes names for the font families to use for roman,
768 sans serif and monospaced text. For example,
770 @cindex font families, setting
779 (make-pango-font-tree "Times New Roman"
786 c'^\markup { roman: foo \sans bla \typewriter bar }
790 @c we don't do Helvetica / Courier, since GS incorrectly loads
794 @node Single entry fonts
795 @subsubsection Single entry fonts
797 @cindex font selection
798 @cindex font magnification
799 @funindex font-interface
801 By setting the object properties described below, you can select a
802 font from the preconfigured font families. LilyPond has default
803 support for the feta music fonts. Text fonts are selected through
804 Pango/FontConfig. The serif font defaults to New Century
805 Schoolbook, the sans and typewriter to whatever the Pango
806 installation defaults to.
810 @item @code{font-encoding}
811 is a symbol that sets layout of the glyphs. This should only be
812 set to select different types of non-text fonts, e.g.
814 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
815 standard music font, including ancient glyphs, @code{fetaDynamic}
816 for dynamic signs and @code{fetaNumber} for the number font.
818 @item @code{font-family}
819 is a symbol indicating the general class of the typeface.
820 Supported are @code{roman} (Computer Modern), @code{sans}, and
823 @item @code{font-shape}
824 is a symbol indicating the shape of the font. There are typically
825 several font shapes available for each font family. Choices are
826 @code{italic}, @code{caps}, and @code{upright}.
828 @item @code{font-series}
829 is a symbol indicating the series of the font. There are
830 typically several font series for each font family and shape.
831 Choices are @code{medium} and @code{bold}.
835 Fonts selected in the way sketched above come from a predefined
836 style sheet. If you want to use a font from outside the style
837 sheet, then set the @code{font-name} property,
839 @lilypond[fragment,verbatim]
841 \override Staff.TimeSignature #'font-name = #"Charter"
842 \override Staff.TimeSignature #'font-size = #2
845 \override #'(font-name . "Vera Bold")
846 { This text is in Vera Bold }
852 Any font can be used, as long as it is available to
853 Pango/FontConfig. To get a full list of all available fonts, run
857 lilypond -dshow-available-fonts blabla
860 (the last argument of the command can be anything, but has to be
864 The size of the font may be set with the @code{font-size}
865 property. The resulting size is taken relative to the
866 @code{text-font-size} as defined in the @code{\paper} block.
869 @cindex font magnification
876 Snippets: @lsrdir{Text,Text}