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
58 Simple @q{quoted text} indications may be added
59 to a score, as demonstrated in the following example.
60 Such indications can be manually placed
61 above or below the staff, using the
62 syntax described in @ref{Direction and
65 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
66 d8^"pizz." e f g a4-"scherz." f
69 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]
91 @funindex \textLengthOn
93 @funindex \textLengthOff
99 Notation Reference: @ref{Formatting text},
100 @ref{Direction and placement}.
105 Internals Reference: @rinternals{TextScript}.
109 Checking to make sure that text scripts and lyrics are within the
110 margins is a relatively large computational task. To speed up
111 processing, LilyPond does not perform such calculations by
112 default; to enable it, use
115 \override Score.PaperColumn #'keep-inside-line = ##t
120 @subsubsection Text spanners
122 @cindex Text spanners
124 Some performance indications, e.g., @notation{rallentando} or
125 @notation{accelerando}, are written as text and are extended over
126 multiple notes with dotted lines.
127 Such objects, called @q{spanners}, may be created
128 from one note to another using the following syntax:
130 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
131 \override TextSpanner #'bound-details #'left #'text = "rit."
137 The string to be printed is set through
138 object properties. By default it is printed in italic characters,
139 but different formatting can be obtained using
140 @code{\markup} blocks, as described in @ref{Formatting text}.
142 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
143 \override TextSpanner #'bound-details #'left #'text =
144 \markup { \upright "rit." }
149 The line style, as well as the text string, can be defined as an
150 object property. This syntax is described in @ref{Line styles}.
154 @funindex textSpannerUp
155 @code{\textSpannerUp},
156 @funindex textSpannerDown
157 @code{\textSpannerDown},
158 @funindex textSpannerNeutral
159 @code{\textSpannerNeutral}
163 Notation Reference: @ref{Line styles}.
168 Internals Reference: @rinternals{TextSpanner}.
172 @subsubsection Text marks
174 @cindex coda on bar line
175 @cindex segno on bar line
176 @cindex fermata on bar line
177 @cindex bar lines, symbols on
180 Various text elements can be added to a score using
181 the syntax described in @ref{Rehearsal marks}:
183 @c \mark needs to be placed on a separate line (it's not
184 @c attached to an object like \markup is). -vv
186 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
192 This syntax makes it possible to put any text on a bar line;
193 more complex text formatting may be added using a @code{\markup}
194 block, as described in @ref{Formatting text}. This can be used to print
195 signs like coda, segno or fermata, by specifying the appropriate
198 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
200 \mark \markup { \musicglyph #"scripts.ufermata" }
205 Such objects are only typeset above the top staff of the score; depending on
206 whether they are specified at the end or the middle of a bar, they
207 can be placed above the bar line or between notes. When specified at the
208 beginning of a score or at a line break, marks will be printed at
209 the beginning of the line (the next line, in case of a line break).
211 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
221 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
222 {printing-marks-at-the-end-of-a-line-or-a-score.ly}
224 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
225 {aligning-marks-with-various-notation-objects.ly}
227 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
228 {printing-marks-on-every-staff.ly}
232 Notation Reference: @ref{Rehearsal marks},
233 @ref{Formatting text}, @ref{The Feta font}.
238 Internals Reference: @rinternals{RehearsalMark}.
241 @c To be removed when Issue 69 in the tracker gets fixed. -vv
243 If a mark is entered at the end of the last bar of the score (where
244 there is no next line), then the mark will not be printed at
248 @subsubsection Separate text
250 @cindex separate text
251 @cindex standalone text
252 @cindex top-level text
253 @cindex text, standalone
256 A @code{\markup} block can exist by itself, outside of any
257 any @code{\score} block, as a @qq{top-level
258 expression}. This syntax is described in @ref{File structure}.
260 @lilypond[verbatim,quote]
262 Tomorrow, and tomorrow, and tomorrow...
267 This allows printing text separately
268 from the music, which is particularly
269 useful when the input file contains
270 several music pieces, as described in
271 @ref{Multiple scores in a book}.
273 @lilypond[quote,ragged-right,verbatim]
278 Tomorrow, and tomorrow, and tomorrow...
285 Using a specific syntax, text blocks can be spread
286 over multiple pages, making possible to print
287 text documents or books -- and therefore to
288 use LilyPond as a word processor. This syntax is described in
289 @ref{Multi-page markup}.
294 @funindex \markuplines
300 TODO: add convenient snippets in input/new -vv
305 Notation Reference: @ref{Formatting text},
306 @ref{File structure},
307 @ref{Multiple scores in a book},
308 @ref{Multi-page markup}.
313 Internals Reference: @rinternals{TextScript}.
316 @node Formatting text
317 @subsection Formatting text
319 This section presents basic and advanced text formatting,
320 using the @code{\markup} mode specific syntax.
323 * Text markup introduction::
324 * Selecting font and font size::
326 * Graphic notation inside markup::
327 * Music notation inside markup::
328 * Multi-page markup::
331 @node Text markup introduction
332 @subsubsection Text markup introduction
340 A @code{\markup} block is used to typeset text with an extensible
341 specific syntax called @qq{markup mode}.
343 @cindex markup expressions
344 @cindex markup syntax
346 The markup syntax is similar to LilyPond's usual syntax: a
347 @code{\markup} expression is enclosed in curly braces @code{@{
350 Unlike simple @q{quoted text} indications, @code{\markup} blocks
351 may contain nested expressions or specific commands,
352 entered using the backslash @code{\} character.
353 Such commands only affect the first following expression.
355 @lilypond[quote,verbatim,fragment,relative=1]
357 a2^\markup { poco \italic più forte }
359 d2_\markup { \italic "string. assai" }
361 b1^\markup { \bold { molto \italic agitato } }
365 @cindex special characters in markup mode
366 @cindex markup mode, special characters
367 @cindex reserved characters, printing
368 @cindex printing special characters
369 @cindex quoted text in markup mode
371 A @code{\markup} block may also contain quoted text, which
372 can be useful to print special characters such as @code{\} and @code{#},
373 or even double quotation marks -- these have to be preceded
376 @lilypond[quote,verbatim,fragment,relative=1]
378 a^\markup "##\ LEPORELLO \##"
379 a_\markup "Bravi! \"Cosa rara\"!"
384 The way markup expressions are defined affects
385 how these expressions will stacked, centered and aligned
386 when using the commands explained in @ref{Text alignment}.
388 @lilypond[quote,verbatim,fragment,relative=1]
389 c1^\markup { \column { a bbbb \line { c d } } }
390 c1^\markup { \center-align { a bbbb c } }
391 c1^\markup { \line { a b c } }
394 Lists of words that are not enclosed with double quotes
395 or preceded by a command are not treated as a distinct
396 expression. In the following example, the first two
397 @code{\markup} expressions are equivalent:
399 @lilypond[quote,verbatim,fragment,relative=1]
400 c1^\markup { \center-align { a bbb c } }
401 c1^\markup { \center-align { a { bbb c } } }
402 c1^\markup { \center-align { a \line { bbb c } } }
406 Markups can be stored in variables. These variables may be
407 directly attached to notes:
409 @lilypond[quote,verbatim]
410 allegro = \markup { \bold \large Allegro }
420 An exhaustive list of @code{\markup}-specific commands can be found in
421 @ref{Text markup commands}.
426 This manual: @ref{Text markup commands}.
431 Internals Reference: @rinternals{TextScript}.
433 Init files: @file{scm/@/new@/-markup@/.scm}.
438 Syntax errors for markup mode can be confusing.
441 @node Selecting font and font size
442 @subsubsection Selecting font and font size
444 @cindex font switching
449 Basic font switching is supported in markup mode:
451 @lilypond[quote,verbatim,relative=2]
455 \italic { non troppo \underline Vivo }
458 d,_\markup { \italic quasi \smallCaps Tromba }
471 The size of the characters can also be altered in different ways:
474 the font size can be defined to an absolute value,
477 predefined commands allow to easily select standard sizes,
480 the font size can also be changed relatively to its previous value.
484 The following example demonstrates these three methods:
486 @lilypond[quote,verbatim,relative=2]
488 f1^\markup { \fontsize #5 Sinfonia }
497 \magnify #0.6 { e sentimento } )
508 Text may be printed as subscript or superscript. By default
509 these are printed in a smaller size, but a normal size can be used as well:
511 @lilypond[quote,verbatim]
514 \line { 1 \super st movement }
515 \line { 1 \normal-size-super st movement
516 \sub { (part two) } }
521 @cindex font families
523 The markup mode provides an easy way to select alternate
524 font families. The default serif font, of roman type, is
525 automatically selected unless specified otherwise: on the
526 last line of the following example, there is no difference
527 between the first and the second word.
529 @lilypond[quote,verbatim]
532 \line { Act \number 1 }
533 \line { \sans { Scene I. } }
534 \line { \typewriter { Verona. An open place. } }
535 \line { Enter \roman Valentine and Proteus. }
541 Some of these font families, used for specific items
542 such as numbers or dynamics, do not provide all
543 characters, as mentioned in @ref{New dynamic marks} and
544 @ref{Manual repeat marks}.
546 @c \concat is actually documented in Align (it is not
547 @c a font-switching command). But we need it here. -vv
549 When used inside a word, some font-switching or formatting
550 commands may produce an unwanted blank space. This can
551 easily be solved by concatenating the text elements together:
553 @lilypond[quote,verbatim]
557 \concat { 1 \super st }
561 \concat { \dynamic p , }
562 \italic { con dolce espressione }
568 An exhaustive list of font-switching, font-size
569 and font-families related commands can be found in @ref{Font}.
571 Defining custom font sets is also possible, as explained in
579 @funindex \normalsize
589 @c TODO: add @seealso
593 @subsubsection Text alignment
595 @cindex text, aligning
596 @cindex aligning text
598 This subsection discusses how to place text in markup mode,
599 inside a @code{\markup} block. Markup objects can also
600 be moved as a whole, using the syntax described in
601 @rlearning{Moving objects}.
603 @c The padding commands should be mentioned on this page, but
604 @c most of these require \box to be more clearly illustrated. -vv
606 @cindex text, horizontal alignment
607 @cindex horizontal text alignment
608 @funindex \left-align
610 @funindex \right-align
612 Markup objects may be aligned in different ways. By default,
613 a text indication is aligned on its left edge: in the following
614 example, there's no difference
615 between the first and the second markup.
617 @lilypond[quote,verbatim,fragment,relative=1]
620 a,-\markup { \left-align poco }
622 a,-\markup { \hcenter { poco } }
624 a,-\markup { \right-align poco }
629 The horizontal alignment may be fine-tuned
630 using a numeric value:
632 @lilypond[quote,verbatim,fragment,relative=1]
633 a1-\markup { \halign #-1 poco }
635 a,-\markup { \halign #0 poco }
637 a,-\markup { \halign #0.5 poco }
639 a,-\markup { \halign #2 poco }
643 Some objects may have alignment procedures of their own,
644 and therefore are not affected by these commands. It is
645 possible to move such markup objects as a whole, as shown
646 for instance in @ref{Text marks},
648 @cindex text, vertical alignment
649 @cindex vertical text alignment
653 Vertical alignment is a bit more complex. As stated above,
654 markup objects can be moved as a whole; however, it is also
655 possible to move specific elements inside a markup block.
656 In this case, the element to be moved needs to be preceded
657 with an @emph{anchor point}, that can be another markup element
658 or an invisible object. The following example demonstrates these
659 two possibilities; the last markup in this example has no anchor
660 point, and therefore is not moved.
662 @lilypond[quote,verbatim,fragment,relative=1]
665 \raise #2 { Scène 1 } }
669 \lower #4 \bold { Très modéré } }
672 \raise #4 \italic { Une forêt. } }
676 @funindex \general-align
678 @funindex \translate-scaled
680 Some commands can affect both the horizontal and vertical
681 alignment of text objects in markup mode. Any object
682 affected by these commands must be preceded with an
685 @lilypond[quote,verbatim,fragment,relative=1]
688 \translate #'(-1 . 2) "Scène 1" }
692 \general-align #Y #3.2 \bold "Très modéré" }
696 \translate-scaled #'(-1 . 2) \teeny "Une forêt." }
700 @cindex multi-line markup
701 @cindex multi-line text
702 @cindex columns, text
704 A markup object may include several lines of text.
705 In the following example, each element or expression
706 is placed on its own line, either left-aligned or centered:
708 @lilypond[quote,verbatim]
724 Similarly, a list of elements or expressions may be
725 spread to fill the entire horizontal line width -- if there
726 is only one element, it will be centered on the page.
727 These expressions can, in turn, include multi-line text
728 or any other markup expression:
730 @lilypond[quote,verbatim]
733 \line { William S. Gilbert }
735 \huge \smallCaps "The Mikado"
737 \smallCaps "The Town of Titipu"
739 \line { Sir Arthur Sullivan }
747 Long text indications can also be automatically wrapped
748 accordingly to the given line width. These will be
749 either left-aligned or justified, as shown in
750 the following example.
752 @lilypond[quote,verbatim]
755 \line \smallCaps { La vida breve }
756 \line \bold { Acto I }
758 (La escena representa el corral de una casa de
759 gitanos en el Albaicín de Granada. Al fondo una
760 puerta por la que se vé el negro interior de
761 una Fragua, iluminado por los rojos resplandores
766 \line \bold { Acto II }
767 \override #'(line-width . 50)
769 (Calle de Granada. Fachada de la casa de Carmela
770 y su hermano Manuel con grandes ventanas abiertas
771 a través de las que se ve el patio
772 donde se celebra una alegre fiesta)
778 An exhaustive list of text alignment commands
779 can be found in @ref{Align}.
781 @c TODO: add @seealso
783 @node Graphic notation inside markup
784 @subsubsection Graphic notation inside markup
786 Graphics around text:
790 (TODO: document padding commands here)
795 "Standalone" graphics:
815 @node Music notation inside markup
816 @subsubsection Music notation inside markup
818 Notes can be printed in markup mode blah blah:
823 Accidental symbols can be obtained easily:
835 Some other notation objects blah blah
843 @c TODO: add \text here? -vv
845 Any musical symbol can be printed
848 @c TODO: add \lookup here? -vv
851 The markup mode has support for fret diagrams:
855 \fret-diagram-verbose
857 An entire @code{\score} block can even be nested in a @code{\markup}
858 block. In such a case, the @code{\score} must contain a @code{\layout} block.
864 @lilypond[quote,verbatim,ragged-right]
868 \relative { c4 d e f }
881 @node Multi-page markup
882 @subsubsection Multi-page markup
884 Whereas @code{\markup} is used to enter a non-breakable block of
885 text, @code{\markuplines} can be used at top-level to enter lines
886 of text that can spread over multiple pages:
891 A very long text of justified lines.
895 An other very long paragraph.
902 @code{\markuplines} accepts a list of markup, that is either the
903 result of a markup list command, or a list of markups or of markup
904 lists. The built-in markup list commands are described in
905 @ref{Text markup list commands}.
909 This manual: @ref{Text markup list commands}, @ref{New
910 markup list command definition}.
917 @funindex \markuplines
925 * Entire document fonts::
926 * Single entry fonts::
929 @node Entire document fonts
930 @subsubsection Entire document fonts
932 It is also possible to change the default font family for the
933 entire document. This is done by calling the
934 @code{make-pango-font-tree} from within the @code{\paper} block.
935 The function takes names for the font families to use for roman,
936 sans serif and monospaced text. For example,
938 @cindex font families, setting
947 (make-pango-font-tree "Times New Roman"
954 c'^\markup { roman: foo \sans bla \typewriter bar }
958 @c we don't do Helvetica / Courier, since GS incorrectly loads
962 @node Single entry fonts
963 @subsubsection Single entry fonts
965 @cindex font selection
966 @cindex font magnification
967 @funindex font-interface
969 By setting the object properties described below, you can select a
970 font from the preconfigured font families. LilyPond has default
971 support for the feta music fonts. Text fonts are selected through
972 Pango/FontConfig. The serif font defaults to New Century
973 Schoolbook, the sans and typewriter to whatever the Pango
974 installation defaults to.
978 @item @code{font-encoding}
979 is a symbol that sets layout of the glyphs. This should only be
980 set to select different types of non-text fonts, e.g.
982 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
983 standard music font, including ancient glyphs, @code{fetaDynamic}
984 for dynamic signs and @code{fetaNumber} for the number font.
986 @item @code{font-family}
987 is a symbol indicating the general class of the typeface.
988 Supported are @code{roman} (Computer Modern), @code{sans}, and
991 @item @code{font-shape}
992 is a symbol indicating the shape of the font. There are typically
993 several font shapes available for each font family. Choices are
994 @code{italic}, @code{caps}, and @code{upright}.
996 @item @code{font-series}
997 is a symbol indicating the series of the font. There are
998 typically several font series for each font family and shape.
999 Choices are @code{medium} and @code{bold}.
1003 Fonts selected in the way sketched above come from a predefined
1004 style sheet. If you want to use a font from outside the style
1005 sheet, then set the @code{font-name} property,
1007 @lilypond[fragment,verbatim]
1009 \override Staff.TimeSignature #'font-name = #"Charter"
1010 \override Staff.TimeSignature #'font-size = #2
1013 \override #'(font-name . "Vera Bold")
1014 { This text is in Vera Bold }
1020 Any font can be used, as long as it is available to
1021 Pango/FontConfig. To get a full list of all available fonts, run
1025 lilypond -dshow-available-fonts blabla
1028 (the last argument of the command can be anything, but has to be
1032 The size of the font may be set with the @code{font-size}
1033 property. The resulting size is taken relative to the
1034 @code{text-font-size} as defined in the @code{\paper} block.
1037 @cindex font magnification