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. For details, see the Contributors'
7 Guide, node Updating translation committishes..
15 @lilypondfile[quote]{text-headword.ly}
17 This section explains how to include text (with various
18 formatting) in music scores.
21 Some text elements that are not dealt with here are discussed in other
22 specific sections: @ref{Vocal music}, @ref{Titles and headers}.
31 @subsection Writing text
33 This section introduces different ways of adding text to a score.
35 @cindex Text, other languages
36 @warning{To write accented and special text (such as characters
37 from other languages), simply insert the characters directly into
38 the LilyPond file. The file must be saved as UTF-8. For more
39 information, see @ref{Text encoding}.}
50 @unnumberedsubsubsec Text scripts
53 @cindex text items, non-empty
54 @cindex non-empty texts
57 Simple @qq{quoted text} indications may be added to a score, as
58 demonstrated in the following example. Such indications may be
59 manually placed above or below the staff, using the syntax described
60 in @ref{Direction and placement}.
62 @lilypond[quote,verbatim]
63 \relative { a'8^"pizz." g f e a4-"scherz." f }
66 This syntax is actually a shorthand; more complex text formatting may be
67 added to a note by explicitly using a @code{\markup} block, as described
68 in @ref{Formatting text}.
70 @lilypond[quote,verbatim]
72 a'8^\markup { \italic pizz. } g f e
73 a4_\markup { \tiny scherz. \bold molto } f }
76 By default, text indications do not influence the note spacing. However,
77 their widths can be taken into account: in the following example, the
78 first text string does not affect spacing, whereas the second one does.
80 @lilypond[quote,verbatim]
88 In addition to text scripts, articulations can be attached to notes.
89 For more information, see @ref{Articulations and ornamentations}.
91 For more information about the relative ordering of text scripts and
92 articulations, see @rlearning{Placement of objects}.
94 @funindex \textLengthOn
95 @funindex textLengthOn
96 @funindex \textLengthOff
97 @funindex textLengthOff
100 @code{\textLengthOn},
101 @code{\textLengthOff}.
106 @rlearning{Placement of objects}.
109 @ref{Formatting text},
110 @ref{Direction and placement},
111 @ref{Articulations and ornamentations}.
117 @rinternals{TextScript}.
119 @cindex text outside margin
120 @cindex margin, text running over
121 @cindex text, keeping inside margin
122 @cindex lyrics, keeping inside margin
125 Checking to make sure that text scripts and lyrics are within the
126 margins requires additonal calculations. In cases where slightly faster
127 performance is desired, use
130 \override Score.PaperColumn.keep-inside-line = ##f
135 @unnumberedsubsubsec Text spanners
137 @cindex text spanners
139 Some performance indications, e.g., @notation{rallentando} or
140 @notation{accelerando}, are written as text and are extended over
141 multiple notes with dotted lines. Such objects, called
142 @qq{spanners}, may be created from one note to another using the
145 @lilypond[verbatim,quote]
147 \override TextSpanner.bound-details.left.text = "rit."
153 @cindex text spanners, formatting
154 @cindex formatting text spanners
157 The string to be printed is set through object properties. By default
158 it is printed in italic characters, but different formatting can be
159 obtained using @code{\markup} blocks, as described in
160 @ref{Formatting text}.
162 @lilypond[quote,verbatim]
164 \override TextSpanner.bound-details.left.text =
165 \markup { \upright "rit." }
171 The line style, as well as the text string, can be defined as an
172 object property. This syntax is described in @ref{Line styles}.
174 @funindex \textSpannerUp
175 @funindex textSpannerUp
176 @funindex \textSpannerDown
177 @funindex textSpannerDown
178 @funindex \textSpannerNeutral
179 @funindex textSpannerNeutral
183 @code{\textSpannerUp},
184 @code{\textSpannerDown},
185 @code{\textSpannerNeutral}.
189 LilyPond is only able to handle one text spanner per voice.
193 @lilypondfile[verbatim,quote,texidoc,doctitle]
194 {dynamics-text-spanner-postfix.ly}
196 @lilypondfile[verbatim,quote,texidoc,doctitle]
197 {dynamics-custom-text-spanner-postfix.ly}
203 @ref{Formatting text}.
207 @rlsr{Expressive marks}.
210 @rinternals{TextSpanner}.
214 @unnumberedsubsubsec Text marks
219 @cindex text on bar line
220 @cindex coda on bar line
221 @cindex segno on bar line
222 @cindex fermata on bar line
223 @cindex bar lines, symbols on
230 Various text elements may be added to a score using the syntax described
231 in @ref{Rehearsal marks}:
233 @c \mark needs to be placed on a separate line (it's not
234 @c attached to an object like \markup is). -vv
236 @lilypond[verbatim,quote]
247 This syntax makes it possible to put any text on a bar line;
248 more complex text formatting may be added using a @code{\markup}
249 block, as described in @ref{Formatting text}:
251 @lilypond[quote,verbatim]
254 \mark \markup { \italic { colla parte } }
261 This syntax also allows to print special signs, like coda, segno
262 or fermata, by specifying the appropriate symbol name as explained in
263 @ref{Music notation inside markup}:
265 @lilypond[quote,verbatim]
268 \mark \markup { \musicglyph #"scripts.ufermata" }
274 Such objects are only typeset above the top staff of the score;
275 depending on whether they are specified at the end or the middle of a
276 bar, they can be placed above the bar line or between notes. When
277 specified at a line break, the mark will be printed at the beginning of
280 @lilypond[quote,verbatim,ragged-right]
289 @funindex \markLengthOn
290 @funindex markLengthOn
291 @funindex \markLengthOff
292 @funindex markLengthOff
295 @code{\markLengthOn},
296 @code{\markLengthOff}.
301 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
302 {printing-marks-at-the-end-of-a-line.ly}
304 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
305 {printing-marks-on-every-staff.ly}
309 @ref{Rehearsal marks},
310 @ref{Formatting text},
311 @ref{Music notation inside markup},
318 @rinternals{MarkEvent},
319 @rinternals{Mark_engraver},
320 @rinternals{RehearsalMark}.
324 @unnumberedsubsubsec Separate text
326 @cindex separate text
327 @cindex text, separate
328 @cindex standalone text
329 @cindex top-level text
330 @cindex text, top-level
331 @cindex text, standalone
336 A @code{\markup} block can exist by itself, outside of any
337 @code{\score} block, as a @qq{top-level expression}. This syntax
338 is described in @ref{File structure}.
340 @lilypond[verbatim,quote]
342 Tomorrow, and tomorrow, and tomorrow...
347 This allows printing text separately from the music, which is
348 particularly useful when the input file contains several music pieces,
349 as described in @ref{Multiple scores in a book}.
351 @lilypond[quote,verbatim]
356 Tomorrow, and tomorrow, and tomorrow...
363 Separate text blocks can be spread over multiple pages,
364 making it possible to print text documents or books entirely
365 within LilyPond. This feature, and the specific syntax it
366 requires, are described in @ref{Multi-page markup}.
371 @funindex \markuplist
382 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
383 {stand-alone-two-column-markup.ly}
387 @ref{Formatting text},
388 @ref{File structure},
389 @ref{Multiple scores in a book},
390 @ref{Multi-page markup}.
396 @rinternals{TextScript}.
399 @node Formatting text
400 @subsection Formatting text
402 This section presents basic and advanced text formatting,
403 using the @code{\markup} mode specific syntax.
406 * Text markup introduction::
407 * Selecting font and font size::
409 * Graphic notation inside markup::
410 * Music notation inside markup::
411 * Multi-page markup::
414 @node Text markup introduction
415 @unnumberedsubsubsec Text markup introduction
425 A @code{\markup} block is used to typeset text with an extensible
426 syntax called @qq{markup mode}.
428 @cindex markup expressions
429 @cindex expressions, markup
430 @cindex markup syntax
431 @cindex syntax, markup
433 The markup syntax is similar to LilyPond's usual syntax: a
434 @code{\markup} expression is enclosed in curly braces
435 @code{@{@dots{} @}}. A single word is regarded as a minimal expression,
436 and therefore does not need to be enclosed with braces.
438 Unlike simple @qq{quoted text} indications, @code{\markup} blocks may
439 contain nested expressions or markup commands, entered using the
440 backslash @code{\} character. Such commands only affect the first
441 following expression.
443 @lilypond[quote,verbatim]
446 a2^\markup { poco \italic più forte }
448 d2_\markup { \italic "string. assai" }
450 b1^\markup { \bold { molto \italic agitato } }
455 @cindex special characters in markup mode
456 @cindex markup mode, special characters
457 @cindex reserved characters, printing
458 @cindex printing reserved characters
459 @cindex printing special characters
460 @cindex quoted text in markup mode
461 @cindex markup mode, quoted text
463 A @code{\markup} block may also contain quoted text strings. Such
464 strings are treated as minimal text expressions, and therefore any
465 markup command or special character (such as @code{\} and@tie{}@code{#})
466 will be printed verbatim without affecting the formatting of the text.
467 Double quotation marks themselves may be printed by preceding them
470 @lilypond[quote,verbatim]
472 a'1^"\italic markup..."
473 a_\markup { \italic "... prints \"italic\" letters!" }
478 To be treated as a distinct expression, a list of words needs to be
479 enclosed with double quotes or preceded by a command. The way markup
480 expressions are defined affects how these expressions will be stacked,
481 centered and aligned; in the following example, the second
482 @code{\markup} expression is treated the same as the first one:
484 @lilypond[quote,verbatim]
486 c1^\markup { \center-column { a bbb c } }
487 c1^\markup { \center-column { a { bbb c } } }
488 c1^\markup { \center-column { a \line { bbb c } } }
489 c1^\markup { \center-column { a "bbb c" } }
493 Markups can be stored in variables. Such variables may be
494 directly attached to notes:
496 @lilypond[quote,verbatim]
497 allegro = \markup { \bold \large Allegro }
507 An exhaustive list of @code{\markup}-specific commands can be found in
508 @ref{Text markup commands}.
512 @ref{Text markup commands}.
518 @file{scm/markup.scm}.
521 Syntax errors for markup mode can be confusing.
524 @node Selecting font and font size
525 @unnumberedsubsubsec Selecting font and font size
527 @cindex font switching
528 @cindex changing fonts
529 @cindex switching fonts
538 Basic font switching is supported in markup mode:
540 @lilypond[quote,verbatim]
544 \italic { non troppo \underline Vivo }
547 d,_\markup { \italic quasi \smallCaps Tromba }
555 @funindex \abs-fontsize
565 The font size can be altered, relative to the global staff size, in a
566 number of different ways
568 It can be set to predefined size,
570 @lilypond[quote,verbatim]
572 b1_\markup { \huge Sinfonia }
573 b1^\markup { \teeny da }
574 b1-\markup { \normalsize camera }
578 It can be set relative to its previous value,
580 @lilypond[quote,verbatim]
582 b1_\markup { \larger Sinfonia }
583 b1^\markup { \smaller da }
584 b1-\markup { \magnify #0.6 camera }
588 It can be increased or decreased relative to the value set by the
591 @lilypond[quote,verbatim]
593 b1_\markup { \fontsize #-2 Sinfonia }
594 b1^\markup { \fontsize #1 da }
595 b1-\markup { \fontsize #3 camera }
599 It can also be set to a fixed point-size, regardless of the global staff
602 @lilypond[quote,verbatim]
604 b1_\markup { \abs-fontsize #20 Sinfonia }
605 b1^\markup { \abs-fontsize #8 da }
606 b1-\markup { \abs-fontsize #14 camera }
610 If the text includes spaces, then it is best to put it all inside quote
611 marks, so that the size of each space is appropriate for the size of the
614 @lilypond[quote,verbatim]
615 \markup \fontsize #6 \bold { Sinfonia da camera }
616 \markup \fontsize #6 \bold { "Sinfonia da camera" }
626 @funindex \normal-size-super
627 @funindex normal-size-super
629 Text may be printed as subscript or superscript. By default these are
630 printed in a smaller size, but a normal size can be used as well:
632 @lilypond[quote,verbatim]
635 \line { 1 \super st movement }
636 \line { 1 \normal-size-super st movement
637 \sub { (part two) } }
642 @cindex font families
644 The markup mode provides an easy way to select alternate font
645 families. The default serif font, of roman type, is automatically
646 selected unless specified otherwise; on the last line of the following
647 example, there is no difference between the first and the second word.
649 @lilypond[quote,verbatim]
652 \line { Act \number 1 }
653 \line { \sans { Scene I. } }
654 \line { \typewriter { Verona. An open place. } }
655 \line { Enter \roman Valentine and Proteus. }
661 Some of these font families, used for specific items such as numbers
662 or dynamics, do not provide all characters, as mentioned in
663 @ref{New dynamic marks} and @ref{Manual repeat marks}.
665 @c \concat is actually documented in Align (it is not
666 @c a font-switching command). But we need it here. -vv
668 When used inside a word, some font-switching or formatting commands
669 may produce an unwanted blank space. This can easily be solved by
670 concatenating the text elements together:
672 @lilypond[quote,verbatim]
676 \concat { 1 \super st }
680 \concat { \dynamic p , }
681 \italic { con dolce espressione }
687 An exhaustive list of font switching commands and custom font usage
688 commands can be found in @ref{Font}.
690 Defining custom font sets is also possible, as explained in
699 @funindex \normalsize
725 @ref{New dynamic marks},
726 @ref{Manual repeat marks},
730 @file{scm/define-markup-commands.scm}.
736 @rinternals{TextScript}.
739 Using the font sizing commands @code{\teeny}, @code{\tiny},
740 @code{\small}, @code{\normalsize}, @code{\large}, and
741 @code{\huge} will lead to inconsistent line spacing compared to
742 using @code{\fontsize}.
746 @unnumberedsubsubsec Text alignment
748 @cindex text, aligning
749 @cindex aligning text
750 @cindex aligning markup text
751 @cindex aligning markups
752 @cindex markups, aligning
753 @cindex markup text, aligning
755 This subsection discusses how to place text in markup mode. Markup
756 objects can also be moved as a whole, using the syntax described in
757 @rlearning{Moving objects}.
759 @c Padding commands should be mentioned on this page, but
760 @c most of these require \box to be more clearly illustrated. -vv
762 @cindex text, horizontal alignment
763 @cindex horizontal text alignment
765 @funindex \left-align
767 @funindex \center-align
768 @funindex center-align
769 @funindex \right-align
770 @funindex right-align
772 Markup objects may be aligned in different ways. By default, a text
773 indication is aligned on its left edge: in the following example,
774 there is no difference between the first and the second markup.
776 @lilypond[quote,verbatim]
778 d''1-\markup { poco }
780 d-\markup { \left-align poco }
782 d-\markup { \center-align { poco } }
784 d-\markup { \right-align poco }
791 Horizontal alignment may be fine-tuned using a numeric value:
793 @lilypond[quote,verbatim]
795 a'1-\markup { \halign #-1 poco }
797 a,-\markup { \halign #0 poco }
799 a,-\markup { \halign #0.5 poco }
801 a,-\markup { \halign #2 poco }
806 Some objects may have alignment procedures of their own, and therefore
807 are not affected by these commands. It is possible to move such
808 markup objects as a whole, as shown for instance in
811 @cindex text, vertical alignment
812 @cindex vertical text alignment
821 @c QUERY Should the function of ``\null'' be clarified? rp
823 Vertical alignment is a bit more complex. As stated above, markup
824 objects can be moved as a whole; however, it is also possible to move
825 specific elements inside a markup block. In this case, the element to
826 be moved needs to be preceded with an @emph{anchor point}, that can be
827 another markup element or an invisible object. The following example
828 demonstrates these two possibilities; the last markup in this example
829 has no anchor point, and therefore is not moved.
831 @lilypond[quote,verbatim]
835 \raise #2 { Scène 1 }
840 \lower #4 \bold { Très modéré }
844 \raise #4 \italic { Une forêt. }
850 @funindex \general-align
851 @funindex general-align
854 @funindex \translate-scaled
855 @funindex translate-scaled
857 Some commands can affect both the horizontal and vertical alignment of
858 text objects in markup mode. Any object affected by these commands
859 must be preceded with an anchor point:
861 @lilypond[quote,verbatim]
865 \translate #'(-1 . 2) "Scène 1"
870 \general-align #Y #3.2 \bold "Très modéré"
875 \translate-scaled #'(-1 . 2) \teeny "Une forêt."
881 @cindex multi-line markup
882 @cindex markup, multi-line
883 @cindex multi-line text
884 @cindex text, multi-line
885 @cindex text in columns
886 @cindex columns, text
890 @funindex \center-column
891 @funindex center-column
893 A markup object may include several lines of text. In the following
894 example, each element or expression is placed on its own line, either
895 left-aligned or centered:
897 @lilypond[quote,verbatim]
913 @cindex centering text on the page
914 @cindex text, centering on the page
915 @cindex markup, centering on the page
920 Similarly, a list of elements or expressions may be spread to fill the
921 entire horizontal line width (if there is only one element, it will be
922 centered on the page). These expressions can, in turn, include
923 multi-line text or any other markup expression:
925 @lilypond[quote,verbatim]
928 \line { William S. Gilbert }
930 \huge \smallCaps "The Mikado"
932 \smallCaps "The Town of Titipu"
934 \line { Sir Arthur Sullivan }
942 @cindex wordwrapped text
943 @cindex justified text
944 @cindex text, justified
945 @cindex text, wordwrapped
946 @cindex markup text, wordwrapped
947 @cindex markup text, justified
954 Long text indications can also be automatically wrapped accordingly to
955 the given line width. These will be either left-aligned or justified,
956 as shown in the following example.
958 @lilypond[quote,verbatim]
961 \line \smallCaps { La vida breve }
962 \line \bold { Acto I }
964 (La escena representa el corral de una casa de
965 gitanos en el AlbaicÃn de Granada. Al fondo una
966 puerta por la que se ve el negro interior de
967 una Fragua, iluminado por los rojos resplandores
972 \line \bold { Acto II }
973 \override #'(line-width . 50)
975 (Calle de Granada. Fachada de la casa de Carmela
976 y su hermano Manuel con grandes ventanas abiertas
977 a través de las que se ve el patio
978 donde se celebra una alegre fiesta)
984 @cindex text alignment commands
985 @cindex markup text alignment commands
986 @cindex alignment, text, commands
988 An exhaustive list of text alignment commands can be found in
993 @rlearning{Moving objects}.
1000 @file{scm/define-markup-commands.scm}.
1005 Internals Reference:
1006 @rinternals{TextScript}.
1009 @node Graphic notation inside markup
1010 @unnumberedsubsubsec Graphic notation inside markup
1012 @cindex graphics, embedding
1013 @cindex drawing graphic objects
1014 @cindex graphic objects, drawing
1015 @cindex embedding graphic objects
1016 @cindex graphic objects, embedding
1018 Various graphic objects may be added to a score, using markup
1021 @cindex decorating text
1022 @cindex framing text
1023 @cindex text, framing
1024 @cindex text, decorating
1025 @cindex markup text, decorating
1026 @cindex markup text, framing
1032 @funindex \rounded-box
1033 @funindex rounded-box
1039 Some markup commands allow decoration of text elements with graphics,
1040 as demonstrated in the following example.
1042 @lilypond[quote,verbatim]
1043 \markup \fill-line {
1051 \bracket "1866 - 1925"
1054 \rounded-box \bold Prelude
1059 @cindex padding around text
1060 @cindex text padding
1061 @cindex markup text padding
1063 @funindex \pad-markup
1064 @funindex pad-markup
1067 @funindex \pad-to-box
1068 @funindex pad-to-box
1069 @funindex \pad-around
1070 @funindex pad-around
1072 Some commands may require an increase in the padding around the text;
1073 this is achieved with some markup commands exhaustively described in
1076 @lilypond[quote,verbatim]
1077 \markup \fill-line {
1079 \box "Charles Ives (1874 - 1954)"
1081 \box \pad-markup #2 "THE UNANSWERED QUESTION"
1082 \box \pad-x #8 "A Cosmic Landscape"
1089 \box \pad-to-box #'(-5 . 20) #'(0 . 5)
1090 \bold "Largo to Presto"
1093 "String quartet keeps very even time,
1094 Flute quartet keeps very uneven time."
1098 @cindex graphic notation
1099 @cindex symbols, non-musical
1100 @cindex non-musical symbols
1101 @cindex notation, graphic
1105 @funindex \draw-circle
1106 @funindex draw-circle
1107 @funindex \filled-box
1108 @funindex filled-box
1111 @funindex \draw-line
1113 @funindex \arrow-head
1114 @funindex arrow-head
1116 Other graphic elements or symbols may be printed without requiring any
1117 text. As with any markup expression, such objects can be combined.
1119 @lilypond[quote,verbatim]
1122 \draw-circle #4 #0.4 ##f
1123 \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
1129 \draw-line #'(0 . 4)
1130 \arrow-head #Y #DOWN ##f
1135 @cindex embedded graphics
1136 @cindex images, embedding
1137 @cindex graphics, embedding
1142 @funindex \postscript
1143 @funindex postscript
1145 Advanced graphic features include the ability to include external
1146 image files converted to the Encapsulated PostScript format
1147 (@emph{eps}), or to directly embed graphics into the input file, using
1148 native PostScript code. In such a case, it may be useful to
1149 explicitly specify the size of the drawing, as demonstrated below:
1151 @lilypond[quote,verbatim,fragment]
1154 \epsfile #X #10 #"./context-example.eps"
1155 \with-dimensions #'(0 . 6) #'(0 . 10)
1171 An exhaustive list of graphics-specific commands can be found in
1178 @ref{Editorial annotations},
1182 @file{scm/define-markup-commands.scm},
1183 @file{scm/stencil.scm}.
1188 Internals Reference:
1189 @rinternals{TextScript}.
1192 @node Music notation inside markup
1193 @unnumberedsubsubsec Music notation inside markup
1195 @cindex notation inside markup
1196 @cindex music inside markup
1197 @cindex markup, music notation inside
1199 Various musical notation elements may be added to a score, inside a
1202 Notes and accidentals can be entered using markup commands:
1204 @lilypond[quote,verbatim,fragment]
1208 \note-by-number #1 #1 #1.5
1211 \natural \semiflat \flat
1212 \sesquiflat \doubleflat
1216 \natural \semisharp \sharp
1217 \sesquisharp \doublesharp
1222 Other notation objects may also be printed
1225 @lilypond[quote,verbatim]
1228 ees\finger \markup \tied-lyric #"4~1"
1229 fis_\markup { \dynamic rf }
1241 More generally, any available musical symbol may be included
1242 separately in a markup object, as demonstrated below; an exhaustive
1243 list of these symbols and their names can be found in
1244 @ref{The Feta font}.
1246 @lilypond[quote,verbatim]
1249 c'^\markup { \musicglyph #"eight" }
1251 c,8._\markup { \musicglyph #"clefs.G_change" }
1253 c2^\markup { \musicglyph #"timesig.neomensural94" }
1257 Another way of printing non-text glyphs is described in
1258 @ref{Fonts explained}. This is useful for printing braces of various
1261 The markup mode also supports diagrams for specific
1264 @lilypond[quote,verbatim]
1267 \fret-diagram-terse #"x;x;o;2;3;2;"
1270 \harp-pedal #"^-v|--ov^"
1275 \musicglyph #"accordion.discant"
1277 \raise #0.5 \musicglyph #"accordion.dot"
1278 \raise #1.5 \musicglyph #"accordion.dot"
1283 @c The accordion diagram is actually taken from a snippet.
1286 Such diagrams are documented in @ref{Instrument Specific Markup}.
1288 @cindex score inside markup
1289 @cindex markup, score inside
1291 A whole score can even be nested inside a markup object. In such a
1292 case, the nested @code{\score} block must contain a @code{\layout}
1293 block, as demonstrated here:
1295 @lilypond[quote,verbatim]
1299 \relative { c'4 d e f }
1308 An exhaustive list of music notation related commands can be found in
1314 @ref{The Feta font},
1315 @ref{Fonts explained}.
1318 @file{scm/define-markup-commands.scm},
1319 @file{scm/fret-diagrams.scm},
1320 @file{scm/harp-pedals.scm}.
1325 Internals Reference:
1326 @rinternals{TextScript}.
1329 @node Multi-page markup
1330 @unnumberedsubsubsec Multi-page markup
1332 @cindex multi-page markup
1333 @cindex markup, multi-page
1334 @cindex markup text, multi-page
1335 @cindex text spread over multiple pages
1337 @funindex \markuplist
1338 @funindex markuplist
1339 @funindex \justified-lines
1340 @funindex justified-lines
1341 @funindex \wordwrap-lines
1342 @funindex wordwrap-lines
1344 Although standard markup objects are not breakable, a specific syntax
1345 makes it possible to enter lines of text that can spread over multiple
1348 @lilypond[quote,verbatim]
1351 A very long text of justified lines.
1355 Another very long paragraph.
1362 This syntax accepts a list of markups, that can be
1365 the result of a markup list command,
1369 a list of markup lists.
1372 An exhaustive list of markup list commands can be found in
1373 @ref{Text markup list commands}.
1377 @ref{Text markup list commands}.
1380 @rextend{New markup list command definition}.
1383 @file{scm/define-markup-commands.scm}.
1388 Internals Reference:
1389 @rinternals{TextScript}.
1391 @funindex \markuplist
1392 @funindex markuplist
1402 This section presents the way fonts are handled, and how they may be
1407 * Single entry fonts::
1408 * Entire document fonts::
1411 @node Fonts explained
1412 @unnumberedsubsubsec Fonts explained
1415 @cindex fonts, explained
1416 @cindex braces, various sizes
1417 @cindex fonts, non-text in markup
1418 @cindex non-text fonts in markup
1420 @funindex font-interface
1422 Fonts are handled through several libraries. FontConfig is used to
1423 detect available fonts on the system; the selected fonts are rendered
1426 Music notation fonts can be described as a set of specific glyphs,
1427 ordered in several families. The following syntax allows various
1428 LilyPond @code{feta} non-text fonts to be used directly in markup
1431 @lilypond[quote,verbatim,fragment]
1434 \override #'(font-encoding . fetaBraces)
1436 \override #'(font-encoding . fetaText)
1438 \override #'(font-encoding . fetaMusic)
1439 \lookup #"noteheads.s0petrucci"
1445 However, all these glyphs except the braces of various sizes contained
1446 in @code{fetaBraces} are available using the simpler syntax described
1447 in @ref{Music notation inside markup}.
1449 When using the glyphs contained in @code{fetaBraces}, the size of the
1450 brace is specified by the numerical part of the glyph name, in
1451 arbitrary units. Any integer from @code{0} to @code{575} inclusive
1452 may be specified, @code{0} giving the smallest brace. The optimum
1453 value must be determined by trial and error. These glyphs are all
1454 left braces; right braces may be obtained by rotation, see
1455 @ref{Rotating objects}.
1457 Three families of text fonts are made available:
1460 The @emph{roman} (serif) font,
1461 which defaults to LilyPond Serif (an alias of TeX Gyre Schola).
1463 The @emph{sans} font,
1464 which defaults to LilyPond Sans Serif (an alias of TeX Gyre Heros).
1466 The @emph{typewriter} (monospaced) font,
1467 which defaults to LilyPond Monospace (an alias of TeX Gyre Cursor).
1470 Each family may include different shapes and series. The following
1471 example demonstrates the ability to select alternate families, shapes,
1472 series and sizes. The value supplied to @code{font-size} is the
1473 required change from the default size.
1475 @lilypond[quote,verbatim,fragment]
1476 \override Score.RehearsalMark.font-family = #'typewriter
1477 \mark \markup "Ouverture"
1478 \override Voice.TextScript.font-shape = #'italic
1479 \override Voice.TextScript.font-series = #'bold
1480 d''2.^\markup "Allegro"
1481 \override Voice.TextScript.font-size = #-3
1486 A similar syntax may be used in markup mode; however in this case it
1487 is preferable to use the simpler syntax explained in
1488 @ref{Selecting font and font size}:
1490 @lilypond[quote,verbatim]
1494 \override #'(font-shape . italic)
1495 \override #'(font-size . 4)
1499 \override #'(font-family . typewriter)
1501 \override #'(font-series . bold)
1505 \override #'(font-family . sans)
1512 Although it is easy to switch between preconfigured fonts, it is also
1513 possible to use other fonts, as explained in the following sections:
1514 @ref{Single entry fonts} and @ref{Entire document fonts}.
1518 @ref{The Feta font},
1519 @ref{Music notation inside markup},
1520 @ref{Rotating objects},
1521 @ref{Selecting font and font size},
1525 @node Single entry fonts
1526 @unnumberedsubsubsec Single entry fonts
1528 Any font that is installed on the operating system and recognized by
1529 FontConfig may be used in a score, using the following syntax:
1531 @lilypond[quote,verbatim,fragment]
1532 \override Staff.TimeSignature.font-name = #"Bitstream Charter"
1533 \override Staff.TimeSignature.font-size = #2
1537 \override #'(font-name . "Bitstream Vera Sans,sans-serif, Oblique Bold")
1538 { Vera Oblique Bold }
1542 @cindex fonts, finding available
1543 @cindex finding available fonts
1544 @cindex listing available fonts
1545 @cindex available fonts, listing
1547 @var{font-name} can be described using a comma-separated list of @q{fonts}
1548 and a white-space separated list of @q{styles}.
1549 As long as the @q{font} in the list is installed
1550 and contains requested glyph, it will be used,
1551 otherwise the @emph{next} font in the list will be used instead.
1553 @funindex show-available-fonts
1555 Running lilypond with the following option displays a list of all
1556 available fonts on the operating system:
1559 lilypond -dshow-available-fonts x
1564 @ref{Fonts explained},
1565 @ref{Entire document fonts}.
1570 @c A source file gets never installed...
1572 @c @file{lily/font-config-scheme.cc}.
1575 @node Entire document fonts
1576 @unnumberedsubsubsec Entire document fonts
1578 It is possible to change the fonts to be used as the default fonts in
1579 the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
1580 specifying them, in that order, as shown in the example below, which
1581 automatically scales the fonts with the value set for the global staff
1582 size. Similar to @ref{Single entry fonts}, it can be described using a
1583 comma-separated list of @q{fonts}. However, font @q{styles} can not be
1584 described. For an explanation of fonts, see @ref{Fonts explained}.
1586 @cindex font families, setting
1587 @cindex fonts, changing for entire document
1589 @funindex make-pango-font-tree
1591 @lilypond[verbatim,quote]
1594 (make-pango-font-tree "Times New Roman"
1595 "Nimbus Sans,Nimbus Sans L"
1597 (/ staff-height pt 20)))
1604 \typewriter typewriter. }
1608 @c we don't do Helvetica / Courier, since GS incorrectly loads
1613 @ref{Fonts explained},
1614 @ref{Single entry fonts},
1615 @ref{Selecting font and font size},