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 may 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{@{
348 @dots{} @}}. A single word is regarded as a minimal expression,
349 and therefore does not need to be enclosed with braces.
351 Unlike simple @q{quoted text} indications, @code{\markup} blocks
352 may contain nested expressions or specific commands,
353 entered using the backslash @code{\} character.
354 Such commands only affect the first following expression.
356 @lilypond[quote,verbatim,fragment,relative=1]
358 a2^\markup { poco \italic più forte }
360 d2_\markup { \italic "string. assai" }
362 b1^\markup { \bold { molto \italic agitato } }
366 @cindex special characters in markup mode
367 @cindex markup mode, special characters
368 @cindex reserved characters, printing
369 @cindex printing special characters
370 @cindex quoted text in markup mode
372 A @code{\markup} block may also contain quoted text strings.
373 Such strings are treated as minimal text expressions, and
374 therefore any markup command or special character (such as
375 @code{\} and @code{#}) will be printed verbatim without affecting
376 the formatting of the text. This syntax even allows to print
377 double quotation marks, by preceding them with backslashes
379 @lilypond[quote,verbatim,fragment,relative=1]
380 d1^"\italic markup..."
381 d_\markup \italic "... prints \"italic\" letters!"
385 The way markup expressions are defined affects
386 how these expressions will be stacked, centered and aligned
387 when using the commands explained in @ref{Text alignment}.
389 @lilypond[quote,verbatim,fragment,relative=1]
390 c1^\markup { \column { a bbbb \line { c d } } }
391 c1^\markup { \center-column { a bbbb c } }
392 c1^\markup { \line { a b c } }
395 Lists of words that are not enclosed with double quotes
396 or preceded by a command are not treated as a distinct
397 expression. In the following example, the first two
398 @code{\markup} expressions are equivalent:
400 @lilypond[quote,verbatim,fragment,relative=1]
401 c1^\markup { \center-column { a bbb c } }
402 c1^\markup { \center-column { a { bbb c } } }
403 c1^\markup { \center-column { a \line { bbb c } } }
407 Markups can be stored in variables. Such variables may be
408 directly attached to notes:
410 @lilypond[quote,verbatim]
411 allegro = \markup { \bold \large Allegro }
421 An exhaustive list of @code{\markup}-specific commands can be found in
422 @ref{Text markup commands}.
428 @ref{Text markup commands}.
434 @rinternals{TextScript}.
437 @file{scm/@/markup@/.scm}.
442 Syntax errors for markup mode can be confusing.
445 @node Selecting font and font size
446 @subsubsection Selecting font and font size
448 @cindex font switching
453 Basic font switching is supported in markup mode:
455 @lilypond[quote,verbatim,relative=2]
459 \italic { non troppo \underline Vivo }
462 d,_\markup { \italic quasi \smallCaps Tromba }
475 The size of the characters can also be altered in different ways:
478 the font size can be defined to an absolute value,
481 predefined commands allow to easily select standard sizes,
484 the font size can also be changed relatively to its previous value.
488 The following example demonstrates these three methods:
490 @lilypond[quote,verbatim,relative=2]
492 f1^\markup { \fontsize #5 Sinfonia }
501 \magnify #0.6 { e sentimento } )
512 Text may be printed as subscript or superscript. By default
513 these are printed in a smaller size, but a normal size can be used as well:
515 @lilypond[quote,verbatim]
518 \line { 1 \super st movement }
519 \line { 1 \normal-size-super st movement
520 \sub { (part two) } }
525 @cindex font families
527 The markup mode provides an easy way to select alternate
528 font families. The default serif font, of roman type, is
529 automatically selected unless specified otherwise: on the
530 last line of the following example, there is no difference
531 between the first and the second word.
533 @lilypond[quote,verbatim]
536 \line { Act \number 1 }
537 \line { \sans { Scene I. } }
538 \line { \typewriter { Verona. An open place. } }
539 \line { Enter \roman Valentine and Proteus. }
545 Some of these font families, used for specific items
546 such as numbers or dynamics, do not provide all
547 characters, as mentioned in @ref{New dynamic marks} and
548 @ref{Manual repeat marks}.
550 @c \concat is actually documented in Align (it is not
551 @c a font-switching command). But we need it here. -vv
553 When used inside a word, some font-switching or formatting
554 commands may produce an unwanted blank space. This can
555 easily be solved by concatenating the text elements together:
557 @lilypond[quote,verbatim]
561 \concat { 1 \super st }
565 \concat { \dynamic p , }
566 \italic { con dolce espressione }
572 An exhaustive list of font-switching, font-size
573 and font-families related commands can be found in @ref{Font}.
575 Defining custom font sets is also possible, as explained in
583 @funindex \normalsize
596 @ref{New dynamic marks},
597 @ref{Manual repeat marks},
604 @rinternals{TextScript}.
607 @file{scm/@/define@/-markup@/-commands@/.scm}.
611 @subsubsection Text alignment
613 @cindex text, aligning
614 @cindex aligning text
616 This subsection discusses how to place text in markup mode,
617 inside a @code{\markup} block. Markup objects can also
618 be moved as a whole, using the syntax described in
619 @rlearning{Moving objects}.
621 @c Padding commands should be mentioned on this page, but
622 @c most of these require \box to be more clearly illustrated. -vv
624 @cindex text, horizontal alignment
625 @cindex horizontal text alignment
626 @funindex \left-align
627 @funindex \center-align
628 @funindex \right-align
630 Markup objects may be aligned in different ways. By default,
631 a text indication is aligned on its left edge: in the following
632 example, there is no difference
633 between the first and the second markup.
635 @lilypond[quote,verbatim,fragment,relative=1]
638 a,-\markup { \left-align poco }
640 a,-\markup { \center-align { poco } }
642 a,-\markup { \right-align poco }
647 Horizontal alignment may be fine-tuned
648 using a numeric value:
650 @lilypond[quote,verbatim,fragment,relative=1]
651 a1-\markup { \halign #-1 poco }
653 a,-\markup { \halign #0 poco }
655 a,-\markup { \halign #0.5 poco }
657 a,-\markup { \halign #2 poco }
661 Some objects may have alignment procedures of their own,
662 and therefore are not affected by these commands. It is
663 possible to move such markup objects as a whole, as shown
664 for instance in @ref{Text marks},
666 @cindex text, vertical alignment
667 @cindex vertical text alignment
671 Vertical alignment is a bit more complex. As stated above,
672 markup objects can be moved as a whole; however, it is also
673 possible to move specific elements inside a markup block.
674 In this case, the element to be moved needs to be preceded
675 with an @emph{anchor point}, that can be another markup element
676 or an invisible object. The following example demonstrates these
677 two possibilities; the last markup in this example has no anchor
678 point, and therefore is not moved.
680 @lilypond[quote,verbatim,fragment,relative=1]
683 \raise #2 { Scène 1 } }
687 \lower #4 \bold { Très modéré } }
690 \raise #4 \italic { Une forêt. } }
694 @funindex \general-align
696 @funindex \translate-scaled
698 Some commands can affect both the horizontal and vertical
699 alignment of text objects in markup mode. Any object
700 affected by these commands must be preceded with an
703 @lilypond[quote,verbatim,fragment,relative=1]
706 \translate #'(-1 . 2) "Scène 1" }
710 \general-align #Y #3.2 \bold "Très modéré" }
714 \translate-scaled #'(-1 . 2) \teeny "Une forêt." }
719 @funindex \center-column
721 @cindex multi-line markup
722 @cindex multi-line text
723 @cindex columns, text
725 A markup object may include several lines of text.
726 In the following example, each element or expression
727 is placed on its own line, either left-aligned or centered:
729 @lilypond[quote,verbatim]
747 @cindex centering text on the page
749 Similarly, a list of elements or expressions may be
750 spread to fill the entire horizontal line width (if there
751 is only one element, it will be centered on the page).
752 These expressions can, in turn, include multi-line text
753 or any other markup expression:
755 @lilypond[quote,verbatim]
758 \line { William S. Gilbert }
760 \huge \smallCaps "The Mikado"
762 \smallCaps "The Town of Titipu"
764 \line { Sir Arthur Sullivan }
775 @cindex wordwrapped text
776 @cindex justified text
778 Long text indications can also be automatically wrapped
779 accordingly to the given line width. These will be
780 either left-aligned or justified, as shown in
781 the following example.
783 @lilypond[quote,verbatim]
786 \line \smallCaps { La vida breve }
787 \line \bold { Acto I }
789 (La escena representa el corral de una casa de
790 gitanos en el AlbaicÃn de Granada. Al fondo una
791 puerta por la que se vé el negro interior de
792 una Fragua, iluminado por los rojos resplandores
797 \line \bold { Acto II }
798 \override #'(line-width . 50)
800 (Calle de Granada. Fachada de la casa de Carmela
801 y su hermano Manuel con grandes ventanas abiertas
802 a través de las que se ve el patio
803 donde se celebra una alegre fiesta)
809 An exhaustive list of text alignment commands
810 can be found in @ref{Align}.
814 @rlearning{Moving objects}.
823 Internals Reference: @rinternals{TextScript}.
826 @file{scm/@/define@/-markup@/-commands@/.scm}.
829 @node Graphic notation inside markup
830 @subsubsection Graphic notation inside markup
832 @cindex graphics, embedding
833 @cindex drawing graphic objects
835 Various graphic objects may be added to a score,
836 using specific markup commands.
840 @funindex \rounded-box
844 @cindex decorating text
847 Some markup commands allow to decorate text elements
848 with graphics, as demonstrated in the following example.
850 @lilypond[quote,verbatim]
859 \bracket "1866 - 1925"
862 \rounded-box \bold Prelude
867 @funindex \pad-markup
869 @funindex \pad-to-box
870 @funindex \pad-around
872 @cindex padding around text
875 Some commands may require to increase the padding around
876 the text: this is achieved with some specific commands
877 exhaustively described in @ref{Align}.
879 @lilypond[quote,verbatim]
882 \box "Charles Ives (1874 - 1954)"
884 \box \pad-markup #2 "THE UNANSWERED QUESTION"
885 \box \pad-x #8 "A Cosmic Landscape"
892 \box \pad-to-box #'(-5 . 20) #'(0 . 5)
893 \bold "Largo to Presto"
896 "String quartet keeps very even time,
897 Flute quartet keeps very uneven time."
902 @funindex \draw-circle
903 @funindex \filled-box
906 @funindex \arrow-head
908 @cindex graphic notation
909 @cindex symbols, non-musical
911 Other graphic elements or symbols may be printed
912 without requiring any text. As with any markup
913 expression, such objects can be combined together:
915 @lilypond[quote,verbatim]
918 \draw-circle #4 #0.4 ##f
919 \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
926 \arrow-head #Y #DOWN ##f
932 @funindex \postscript
934 @cindex embedded graphics
935 @cindex images, embedding
936 @cindex graphics, embedding
939 Advanced graphic features include the ability to
940 include external image files converted to the
941 Encapsulated PostScript format (@emph{eps}), or
942 to directly embed graphics into the input file,
943 using native PostScript code.
945 @lilypond[quote,verbatim,fragment,relative=1]
948 \epsfile #X #10 #"./context-example.eps"
964 An exhaustive list of graphics-specific commands
965 can be found in @ref{Graphic}.
970 @ref{Editorial annotations}.
975 Internals Reference: @rinternals{TextScript}.
978 @file{scm/@/define@/-markup@/-commands@/.scm},
979 @file{scm/@/stencil@/.scm}.
981 @node Music notation inside markup
982 @subsubsection Music notation inside markup
984 Various musical notation elements may be added
985 to a score, inside a markup object.
987 Notes and accidentals can be entered using specific
990 @lilypond[quote,verbatim,fragment,relative=2]
994 \note-by-number #1 #1 #1.5
997 \natural \semiflat \flat
998 \sesquiflat \doubleflat
1002 \natural \semisharp \sharp
1003 \sesquisharp \doublesharp
1008 Other notation objects may also be printed
1011 @lilypond[quote,verbatim,fragment,relative=1]
1018 fis_\markup { \dynamic rf }
1029 More generally, any available musical symbol may be
1030 included separately in a markup object, using the
1033 @lilypond[quote,verbatim,fragment,relative=2]
1035 c'^\markup { \musicglyph #"eight" }
1037 c,8._\markup { \musicglyph #"clefs.G_change" }
1039 c2^\markup { \musicglyph #"timesig.neomensural94" }
1041 @c TODO: add \lookup here? -vv
1044 An exhaustive list of these symbols and their names can
1045 be found in @ref{The Feta font}.
1047 The markup mode also supports diagrams for specific
1050 @lilypond[quote,verbatim,fragment,relative=2]
1052 \fret-diagram-terse #"x;x;o;2;3;2;"
1055 \harp-pedal #"^-v|--ov^"
1060 \musicglyph #"accordion.accDiscant"
1062 \raise #0.5 \musicglyph #"accordion.accDot"
1063 \raise #1.5 \musicglyph #"accordion.accDot"
1067 @c The accordion diagram is actually taken from a snippet.
1070 Such diagrams are documented in @ref{Instrument Specific Markup}.
1072 A whole score can even be nested inside a markup object.
1073 In such a case, the nested @code{\score} block must
1074 contain a @code{\layout} block, as demonstrated here:
1076 @lilypond[quote,verbatim,fragment,relative=1]
1079 \relative { c4 d e f }
1087 An exhaustive list of music notation related commands can be
1088 found in @ref{Music}.
1093 @ref{The Feta font}.
1098 Internals Reference: @rinternals{TextScript}.
1101 @file{scm/@/define@/-markup@/-commands@/.scm},
1102 @file{scm/@/fret@/-diagrams@/.scm},
1103 @file{scm/@/harp@/-pedals@/.scm}.
1105 @node Multi-page markup
1106 @subsubsection Multi-page markup
1108 Although standard markup objects are not breakable, a
1109 specific syntax allows to enter lines of text that can
1110 spread over multiple pages:
1112 @lilypond[quote,verbatim]
1115 A very long text of justified lines.
1119 An other very long paragraph.
1126 This specific syntax accepts a list of markups, that can be
1129 the result of a markup list command,
1133 a list of markup lists.
1136 An exhaustive list of markup list commands can be found in
1137 @ref{Text markup list commands}.
1141 @ref{Text markup list commands},
1142 @ref{New markup list command definition}.
1147 Internals Reference: @rinternals{TextScript}.
1150 @file{scm/@/define@/-markup@/-commands@/.scm}.
1153 @funindex \markuplines
1161 * Entire document fonts::
1162 * Single entry fonts::
1165 @node Entire document fonts
1166 @subsubsection Entire document fonts
1168 It is also possible to change the default font family for the
1169 entire document. This is done by calling the
1170 @code{make-pango-font-tree} from within the @code{\paper} block.
1171 The function takes names for the font families to use for roman,
1172 sans serif and monospaced text. For example,
1174 @cindex font families, setting
1183 (make-pango-font-tree "Times New Roman"
1186 (/ myStaffSize 20)))
1190 c'^\markup { roman: foo \sans bla \typewriter bar }
1194 @c we don't do Helvetica / Courier, since GS incorrectly loads
1198 @node Single entry fonts
1199 @subsubsection Single entry fonts
1201 @cindex font selection
1202 @cindex font magnification
1203 @funindex font-interface
1205 By setting the object properties described below, you can select a
1206 font from the preconfigured font families. LilyPond has default
1207 support for the feta music fonts. Text fonts are selected through
1208 Pango/FontConfig. The serif font defaults to New Century
1209 Schoolbook, the sans and typewriter to whatever the Pango
1210 installation defaults to.
1214 @item @code{font-encoding}
1215 is a symbol that sets layout of the glyphs. This should only be
1216 set to select different types of non-text fonts, e.g.
1218 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
1219 standard music font, including ancient glyphs, @code{fetaDynamic}
1220 for dynamic signs and @code{fetaNumber} for the number font.
1222 @item @code{font-family}
1223 is a symbol indicating the general class of the typeface.
1224 Supported are @code{roman} (Computer Modern), @code{sans}, and
1227 @item @code{font-shape}
1228 is a symbol indicating the shape of the font. There are typically
1229 several font shapes available for each font family. Choices are
1230 @code{italic}, @code{caps}, and @code{upright}.
1232 @item @code{font-series}
1233 is a symbol indicating the series of the font. There are
1234 typically several font series for each font family and shape.
1235 Choices are @code{medium} and @code{bold}.
1239 Fonts selected in the way sketched above come from a predefined
1240 style sheet. If you want to use a font from outside the style
1241 sheet, then set the @code{font-name} property,
1243 @lilypond[fragment,verbatim]
1245 \override Staff.TimeSignature #'font-name = #"Charter"
1246 \override Staff.TimeSignature #'font-size = #2
1249 \override #'(font-name . "Vera Bold")
1250 { This text is in Vera Bold }
1256 Any font can be used, as long as it is available to
1257 Pango/FontConfig. To get a full list of all available fonts, run
1261 lilypond -dshow-available-fonts blabla
1264 (the last argument of the command can be anything, but has to be
1268 The size of the font may be set with the @code{font-size}
1269 property. The resulting size is taken relative to the
1270 @code{text-font-size} as defined in the @code{\paper} block.
1273 @cindex font magnification