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]
244 This syntax makes it possible to put any text on a bar line;
245 more complex text formatting may be added using a @code{\markup}
246 block, as described in @ref{Formatting text}:
248 @lilypond[quote,verbatim]
251 \mark \markup { \italic { colla parte } }
258 This syntax also allows to print special signs, like coda, segno
259 or fermata, by specifying the appropriate symbol name as explained in
260 @ref{Music notation inside markup}:
262 @lilypond[quote,verbatim]
265 \mark \markup { \musicglyph #"scripts.ufermata" }
271 Such objects are only typeset above the top staff of the score;
272 depending on whether they are specified at the end or the middle of a
273 bar, they can be placed above the bar line or between notes. When
274 specified at a line break, the mark will be printed at the beginning of
277 @lilypond[quote,verbatim,ragged-right]
286 @funindex \markLengthOn
287 @funindex markLengthOn
288 @funindex \markLengthOff
289 @funindex markLengthOff
292 @code{\markLengthOn},
293 @code{\markLengthOff}.
298 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
299 {printing-marks-at-the-end-of-a-line.ly}
301 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
302 {printing-marks-on-every-staff.ly}
306 @ref{Rehearsal marks},
307 @ref{Formatting text},
308 @ref{Music notation inside markup},
315 @rinternals{MarkEvent},
316 @rinternals{Mark_engraver},
317 @rinternals{RehearsalMark}.
321 @unnumberedsubsubsec Separate text
323 @cindex separate text
324 @cindex text, separate
325 @cindex standalone text
326 @cindex top-level text
327 @cindex text, top-level
328 @cindex text, standalone
333 A @code{\markup} block can exist by itself, outside of any
334 @code{\score} block, as a @qq{top-level expression}. This syntax
335 is described in @ref{File structure}.
337 @lilypond[verbatim,quote]
339 Tomorrow, and tomorrow, and tomorrow...
344 This allows printing text separately from the music, which is
345 particularly useful when the input file contains several music pieces,
346 as described in @ref{Multiple scores in a book}.
348 @lilypond[quote,verbatim]
353 Tomorrow, and tomorrow, and tomorrow...
360 Separate text blocks can be spread over multiple pages,
361 making it possible to print text documents or books entirely
362 within LilyPond. This feature, and the specific syntax it
363 requires, are described in @ref{Multi-page markup}.
368 @funindex \markuplist
379 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
380 {stand-alone-two-column-markup.ly}
384 @ref{Formatting text},
385 @ref{File structure},
386 @ref{Multiple scores in a book},
387 @ref{Multi-page markup}.
393 @rinternals{TextScript}.
396 @node Formatting text
397 @subsection Formatting text
399 This section presents basic and advanced text formatting,
400 using the @code{\markup} mode specific syntax.
403 * Text markup introduction::
404 * Selecting font and font size::
406 * Graphic notation inside markup::
407 * Music notation inside markup::
408 * Multi-page markup::
411 @node Text markup introduction
412 @unnumberedsubsubsec Text markup introduction
422 A @code{\markup} block is used to typeset text with an extensible
423 syntax called @qq{markup mode}.
425 @cindex markup expressions
426 @cindex expressions, markup
427 @cindex markup syntax
428 @cindex syntax, markup
430 The markup syntax is similar to LilyPond's usual syntax: a
431 @code{\markup} expression is enclosed in curly braces
432 @code{@{@dots{} @}}. A single word is regarded as a minimal expression,
433 and therefore does not need to be enclosed with braces.
435 Unlike simple @qq{quoted text} indications, @code{\markup} blocks may
436 contain nested expressions or markup commands, entered using the
437 backslash @code{\} character. Such commands only affect the first
438 following expression.
440 @lilypond[quote,verbatim]
443 a2^\markup { poco \italic più forte }
445 d2_\markup { \italic "string. assai" }
447 b1^\markup { \bold { molto \italic agitato } }
452 @cindex special characters in markup mode
453 @cindex markup mode, special characters
454 @cindex reserved characters, printing
455 @cindex printing reserved characters
456 @cindex printing special characters
457 @cindex quoted text in markup mode
458 @cindex markup mode, quoted text
460 A @code{\markup} block may also contain quoted text strings. Such
461 strings are treated as minimal text expressions, and therefore any
462 markup command or special character (such as @code{\} and@tie{}@code{#})
463 will be printed verbatim without affecting the formatting of the text.
464 Double quotation marks themselves may be printed by preceding them
467 @lilypond[quote,verbatim]
469 a'1^"\italic markup..."
470 a_\markup { \italic "... prints \"italic\" letters!" }
475 To be treated as a distinct expression, a list of words needs to be
476 enclosed with double quotes or preceded by a command. The way markup
477 expressions are defined affects how these expressions will be stacked,
478 centered and aligned; in the following example, the second
479 @code{\markup} expression is treated the same as the first one:
481 @lilypond[quote,verbatim]
483 c1^\markup { \center-column { a bbb c } }
484 c1^\markup { \center-column { a { bbb c } } }
485 c1^\markup { \center-column { a \line { bbb c } } }
486 c1^\markup { \center-column { a "bbb c" } }
490 Markups can be stored in variables. Such variables may be
491 directly attached to notes:
493 @lilypond[quote,verbatim]
494 allegro = \markup { \bold \large Allegro }
504 An exhaustive list of @code{\markup}-specific commands can be found in
505 @ref{Text markup commands}.
509 @ref{Text markup commands}.
515 @file{scm/markup.scm}.
518 Syntax errors for markup mode can be confusing.
521 @node Selecting font and font size
522 @unnumberedsubsubsec Selecting font and font size
524 @cindex font switching
525 @cindex changing fonts
526 @cindex switching fonts
535 Basic font switching is supported in markup mode:
537 @lilypond[quote,verbatim]
541 \italic { non troppo \underline Vivo }
544 d,_\markup { \italic quasi \smallCaps Tromba }
552 @funindex \abs-fontsize
562 The font size can be altered, relative to the global staff size, in a
563 number of different ways
565 It can be set to predefined size,
567 @lilypond[quote,verbatim]
569 b1_\markup { \huge Sinfonia }
570 b1^\markup { \teeny da }
571 b1-\markup { \normalsize camera }
575 It can be set relative to its previous value,
577 @lilypond[quote,verbatim]
579 b1_\markup { \larger Sinfonia }
580 b1^\markup { \smaller da }
581 b1-\markup { \magnify #0.6 camera }
585 It can be increased or decreased relative to the value set by the
588 @lilypond[quote,verbatim]
590 b1_\markup { \fontsize #-2 Sinfonia }
591 b1^\markup { \fontsize #1 da }
592 b1-\markup { \fontsize #3 camera }
596 It can also be set to a fixed point-size, regardless of the global staff
599 @lilypond[quote,verbatim]
601 b1_\markup { \abs-fontsize #20 Sinfonia }
602 b1^\markup { \abs-fontsize #8 da }
603 b1-\markup { \abs-fontsize #14 camera }
607 If the text includes spaces, then it is best to put it all inside quote
608 marks, so that the size of each space is appropriate for the size of the
611 @lilypond[quote,verbatim]
612 \markup \fontsize #6 \bold { Sinfonia da camera }
613 \markup \fontsize #6 \bold { "Sinfonia da camera" }
623 @funindex \normal-size-super
624 @funindex normal-size-super
626 Text may be printed as subscript or superscript. By default these are
627 printed in a smaller size, but a normal size can be used as well:
629 @lilypond[quote,verbatim]
632 \line { 1 \super st movement }
633 \line { 1 \normal-size-super st movement
634 \sub { (part two) } }
639 @cindex font families
641 The markup mode provides an easy way to select alternate font
642 families. The default serif font, of roman type, is automatically
643 selected unless specified otherwise; on the last line of the following
644 example, there is no difference between the first and the second word.
646 @lilypond[quote,verbatim]
649 \line { Act \number 1 }
650 \line { \sans { Scene I. } }
651 \line { \typewriter { Verona. An open place. } }
652 \line { Enter \roman Valentine and Proteus. }
658 Some of these font families, used for specific items such as numbers
659 or dynamics, do not provide all characters, as mentioned in
660 @ref{New dynamic marks} and @ref{Manual repeat marks}.
662 @c \concat is actually documented in Align (it is not
663 @c a font-switching command). But we need it here. -vv
665 When used inside a word, some font-switching or formatting commands
666 may produce an unwanted blank space. This can easily be solved by
667 concatenating the text elements together:
669 @lilypond[quote,verbatim]
673 \concat { 1 \super st }
677 \concat { \dynamic p , }
678 \italic { con dolce espressione }
684 An exhaustive list of font switching commands and custom font usage
685 commands can be found in @ref{Font}.
687 Defining custom font sets is also possible, as explained in
696 @funindex \normalsize
722 @ref{New dynamic marks},
723 @ref{Manual repeat marks},
727 @file{scm/define-markup-commands.scm}.
733 @rinternals{TextScript}.
736 Using the font sizing commands @code{\teeny}, @code{\tiny},
737 @code{\small}, @code{\normalsize}, @code{\large}, and
738 @code{\huge} will lead to inconsistent line spacing compared to
739 using @code{\fontsize}.
743 @unnumberedsubsubsec Text alignment
745 @cindex text, aligning
746 @cindex aligning text
747 @cindex aligning markup text
748 @cindex aligning markups
749 @cindex markups, aligning
750 @cindex markup text, aligning
752 This subsection discusses how to place text in markup mode. Markup
753 objects can also be moved as a whole, using the syntax described in
754 @rlearning{Moving objects}.
756 @c Padding commands should be mentioned on this page, but
757 @c most of these require \box to be more clearly illustrated. -vv
759 @cindex text, horizontal alignment
760 @cindex horizontal text alignment
762 @funindex \left-align
764 @funindex \center-align
765 @funindex center-align
766 @funindex \right-align
767 @funindex right-align
769 Markup objects may be aligned in different ways. By default, a text
770 indication is aligned on its left edge: in the following example,
771 there is no difference between the first and the second markup.
773 @lilypond[quote,verbatim]
775 d''1-\markup { poco }
777 d-\markup { \left-align poco }
779 d-\markup { \center-align { poco } }
781 d-\markup { \right-align poco }
788 Horizontal alignment may be fine-tuned using a numeric value:
790 @lilypond[quote,verbatim]
792 a'1-\markup { \halign #-1 poco }
794 a,-\markup { \halign #0 poco }
796 a,-\markup { \halign #0.5 poco }
798 a,-\markup { \halign #2 poco }
803 Some objects may have alignment procedures of their own, and therefore
804 are not affected by these commands. It is possible to move such
805 markup objects as a whole, as shown for instance in
808 @cindex text, vertical alignment
809 @cindex vertical text alignment
818 @c QUERY Should the function of ``\null'' be clarified? rp
820 Vertical alignment is a bit more complex. As stated above, markup
821 objects can be moved as a whole; however, it is also possible to move
822 specific elements inside a markup block. In this case, the element to
823 be moved needs to be preceded with an @emph{anchor point}, that can be
824 another markup element or an invisible object. The following example
825 demonstrates these two possibilities; the last markup in this example
826 has no anchor point, and therefore is not moved.
828 @lilypond[quote,verbatim]
832 \raise #2 { Scène 1 }
837 \lower #4 \bold { Très modéré }
841 \raise #4 \italic { Une forêt. }
847 @funindex \general-align
848 @funindex general-align
851 @funindex \translate-scaled
852 @funindex translate-scaled
854 Some commands can affect both the horizontal and vertical alignment of
855 text objects in markup mode. Any object affected by these commands
856 must be preceded with an anchor point:
858 @lilypond[quote,verbatim]
862 \translate #'(-1 . 2) "Scène 1"
867 \general-align #Y #3.2 \bold "Très modéré"
872 \translate-scaled #'(-1 . 2) \teeny "Une forêt."
878 @cindex multi-line markup
879 @cindex markup, multi-line
880 @cindex multi-line text
881 @cindex text, multi-line
882 @cindex text in columns
883 @cindex columns, text
887 @funindex \center-column
888 @funindex center-column
890 A markup object may include several lines of text. In the following
891 example, each element or expression is placed on its own line, either
892 left-aligned or centered:
894 @lilypond[quote,verbatim]
910 @cindex centering text on the page
911 @cindex text, centering on the page
912 @cindex markup, centering on the page
917 Similarly, a list of elements or expressions may be spread to fill the
918 entire horizontal line width (if there is only one element, it will be
919 centered on the page). These expressions can, in turn, include
920 multi-line text or any other markup expression:
922 @lilypond[quote,verbatim]
925 \line { William S. Gilbert }
927 \huge \smallCaps "The Mikado"
929 \smallCaps "The Town of Titipu"
931 \line { Sir Arthur Sullivan }
939 @cindex wordwrapped text
940 @cindex justified text
941 @cindex text, justified
942 @cindex text, wordwrapped
943 @cindex markup text, wordwrapped
944 @cindex markup text, justified
951 Long text indications can also be automatically wrapped accordingly to
952 the given line width. These will be either left-aligned or justified,
953 as shown in the following example.
955 @lilypond[quote,verbatim]
958 \line \smallCaps { La vida breve }
959 \line \bold { Acto I }
961 (La escena representa el corral de una casa de
962 gitanos en el AlbaicÃn de Granada. Al fondo una
963 puerta por la que se ve el negro interior de
964 una Fragua, iluminado por los rojos resplandores
969 \line \bold { Acto II }
970 \override #'(line-width . 50)
972 (Calle de Granada. Fachada de la casa de Carmela
973 y su hermano Manuel con grandes ventanas abiertas
974 a través de las que se ve el patio
975 donde se celebra una alegre fiesta)
981 @cindex text alignment commands
982 @cindex markup text alignment commands
983 @cindex alignment, text, commands
985 An exhaustive list of text alignment commands can be found in
990 @rlearning{Moving objects}.
997 @file{scm/define-markup-commands.scm}.
1002 Internals Reference:
1003 @rinternals{TextScript}.
1006 @node Graphic notation inside markup
1007 @unnumberedsubsubsec Graphic notation inside markup
1009 @cindex graphics, embedding
1010 @cindex drawing graphic objects
1011 @cindex graphic objects, drawing
1012 @cindex embedding graphic objects
1013 @cindex graphic objects, embedding
1015 Various graphic objects may be added to a score, using markup
1018 @cindex decorating text
1019 @cindex framing text
1020 @cindex text, framing
1021 @cindex text, decorating
1022 @cindex markup text, decorating
1023 @cindex markup text, framing
1029 @funindex \rounded-box
1030 @funindex rounded-box
1036 Some markup commands allow decoration of text elements with graphics,
1037 as demonstrated in the following example.
1039 @lilypond[quote,verbatim]
1040 \markup \fill-line {
1048 \bracket "1866 - 1925"
1051 \rounded-box \bold Prelude
1056 @cindex padding around text
1057 @cindex text padding
1058 @cindex markup text padding
1060 @funindex \pad-markup
1061 @funindex pad-markup
1064 @funindex \pad-to-box
1065 @funindex pad-to-box
1066 @funindex \pad-around
1067 @funindex pad-around
1069 Some commands may require an increase in the padding around the text;
1070 this is achieved with some markup commands exhaustively described in
1073 @lilypond[quote,verbatim]
1074 \markup \fill-line {
1076 \box "Charles Ives (1874 - 1954)"
1078 \box \pad-markup #2 "THE UNANSWERED QUESTION"
1079 \box \pad-x #8 "A Cosmic Landscape"
1086 \box \pad-to-box #'(-5 . 20) #'(0 . 5)
1087 \bold "Largo to Presto"
1090 "String quartet keeps very even time,
1091 Flute quartet keeps very uneven time."
1095 @cindex graphic notation
1096 @cindex symbols, non-musical
1097 @cindex non-musical symbols
1098 @cindex notation, graphic
1102 @funindex \draw-circle
1103 @funindex draw-circle
1104 @funindex \filled-box
1105 @funindex filled-box
1108 @funindex \draw-line
1110 @funindex \arrow-head
1111 @funindex arrow-head
1113 Other graphic elements or symbols may be printed without requiring any
1114 text. As with any markup expression, such objects can be combined.
1116 @lilypond[quote,verbatim]
1119 \draw-circle #4 #0.4 ##f
1120 \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
1126 \draw-line #'(0 . 4)
1127 \arrow-head #Y #DOWN ##f
1132 @cindex embedded graphics
1133 @cindex images, embedding
1134 @cindex graphics, embedding
1139 @funindex \postscript
1140 @funindex postscript
1142 Advanced graphic features include the ability to include external
1143 image files converted to the Encapsulated PostScript format
1144 (@emph{eps}), or to directly embed graphics into the input file, using
1145 native PostScript code. In such a case, it may be useful to
1146 explicitly specify the size of the drawing, as demonstrated below:
1148 @lilypond[quote,verbatim,fragment]
1151 \epsfile #X #10 #"./context-example.eps"
1152 \with-dimensions #'(0 . 6) #'(0 . 10)
1168 An exhaustive list of graphics-specific commands can be found in
1175 @ref{Editorial annotations},
1179 @file{scm/define-markup-commands.scm},
1180 @file{scm/stencil.scm}.
1185 Internals Reference:
1186 @rinternals{TextScript}.
1189 @node Music notation inside markup
1190 @unnumberedsubsubsec Music notation inside markup
1192 @cindex notation inside markup
1193 @cindex music inside markup
1194 @cindex markup, music notation inside
1196 Various musical notation elements may be added to a score, inside a
1199 Notes and accidentals can be entered using markup commands:
1201 @lilypond[quote,verbatim,fragment]
1205 \note-by-number #1 #1 #1.5
1208 \natural \semiflat \flat
1209 \sesquiflat \doubleflat
1213 \natural \semisharp \sharp
1214 \sesquisharp \doublesharp
1219 Other notation objects may also be printed
1222 @lilypond[quote,verbatim]
1225 ees\finger \markup \tied-lyric #"4~1"
1226 fis_\markup { \dynamic rf }
1238 More generally, any available musical symbol may be included
1239 separately in a markup object, as demonstrated below; an exhaustive
1240 list of these symbols and their names can be found in
1241 @ref{The Feta font}.
1243 @lilypond[quote,verbatim]
1246 c'^\markup { \musicglyph #"eight" }
1248 c,8._\markup { \musicglyph #"clefs.G_change" }
1250 c2^\markup { \musicglyph #"timesig.neomensural94" }
1254 Another way of printing non-text glyphs is described in
1255 @ref{Fonts explained}. This is useful for printing braces of various
1258 The markup mode also supports diagrams for specific
1261 @lilypond[quote,verbatim]
1264 \fret-diagram-terse #"x;x;o;2;3;2;"
1267 \harp-pedal #"^-v|--ov^"
1272 \musicglyph #"accordion.discant"
1274 \raise #0.5 \musicglyph #"accordion.dot"
1275 \raise #1.5 \musicglyph #"accordion.dot"
1280 @c The accordion diagram is actually taken from a snippet.
1283 Such diagrams are documented in @ref{Instrument Specific Markup}.
1285 @cindex score inside markup
1286 @cindex markup, score inside
1288 A whole score can even be nested inside a markup object. In such a
1289 case, the nested @code{\score} block must contain a @code{\layout}
1290 block, as demonstrated here:
1292 @lilypond[quote,verbatim]
1296 \relative { c'4 d e f }
1305 An exhaustive list of music notation related commands can be found in
1311 @ref{The Feta font},
1312 @ref{Fonts explained}.
1315 @file{scm/define-markup-commands.scm},
1316 @file{scm/fret-diagrams.scm},
1317 @file{scm/harp-pedals.scm}.
1322 Internals Reference:
1323 @rinternals{TextScript}.
1326 @node Multi-page markup
1327 @unnumberedsubsubsec Multi-page markup
1329 @cindex multi-page markup
1330 @cindex markup, multi-page
1331 @cindex markup text, multi-page
1332 @cindex text spread over multiple pages
1334 @funindex \markuplist
1335 @funindex markuplist
1336 @funindex \justified-lines
1337 @funindex justified-lines
1338 @funindex \wordwrap-lines
1339 @funindex wordwrap-lines
1341 Although standard markup objects are not breakable, a specific syntax
1342 makes it possible to enter lines of text that can spread over multiple
1345 @lilypond[quote,verbatim]
1348 A very long text of justified lines.
1352 Another very long paragraph.
1359 This syntax accepts a list of markups, that can be
1362 the result of a markup list command,
1366 a list of markup lists.
1369 An exhaustive list of markup list commands can be found in
1370 @ref{Text markup list commands}.
1374 @ref{Text markup list commands}.
1377 @rextend{New markup list command definition}.
1380 @file{scm/define-markup-commands.scm}.
1385 Internals Reference:
1386 @rinternals{TextScript}.
1388 @funindex \markuplist
1389 @funindex markuplist
1399 This section presents the way fonts are handled, and how they may be
1404 * Single entry fonts::
1405 * Entire document fonts::
1408 @node Fonts explained
1409 @unnumberedsubsubsec Fonts explained
1412 @cindex fonts, explained
1413 @cindex braces, various sizes
1414 @cindex fonts, non-text in markup
1415 @cindex non-text fonts in markup
1417 @funindex font-interface
1419 Fonts are handled through several libraries. FontConfig is used to
1420 detect available fonts on the system; the selected fonts are rendered
1423 Music notation fonts can be described as a set of specific glyphs,
1424 ordered in several families. The following syntax allows various
1425 LilyPond @code{feta} non-text fonts to be used directly in markup
1428 @lilypond[quote,verbatim,fragment]
1431 \override #'(font-encoding . fetaBraces)
1433 \override #'(font-encoding . fetaText)
1435 \override #'(font-encoding . fetaMusic)
1436 \lookup #"noteheads.s0petrucci"
1442 However, all these glyphs except the braces of various sizes contained
1443 in @code{fetaBraces} are available using the simpler syntax described
1444 in @ref{Music notation inside markup}.
1446 When using the glyphs contained in @code{fetaBraces}, the size of the
1447 brace is specified by the numerical part of the glyph name, in
1448 arbitrary units. Any integer from @code{0} to @code{575} inclusive
1449 may be specified, @code{0} giving the smallest brace. The optimum
1450 value must be determined by trial and error. These glyphs are all
1451 left braces; right braces may be obtained by rotation, see
1452 @ref{Rotating objects}.
1454 Three families of text fonts are made available: the @emph{roman}
1455 (serif) font, that defaults to New Century Schoolbook, the
1456 @emph{sans} font and the monospaced @emph{typewriter} font -- these
1457 last two families are determined by the Pango installation.
1459 @warning{There are no default fonts associated with the @emph{sans}
1460 and @emph{typewriter} font-families. An input file that specifies
1461 either of these can lead to different output on different computers.
1462 To ensure consistent output among multiple platforms, fonts must be
1463 specified by name, and those fonts must be available on any system
1464 that processes the file. See @ref{Single entry fonts} and
1465 @ref{Entire document fonts}.}
1467 Each family may include different shapes and series. The following
1468 example demonstrates the ability to select alternate families, shapes,
1469 series and sizes. The value supplied to @code{font-size} is the
1470 required change from the default size.
1472 @lilypond[quote,verbatim,fragment]
1473 \override Score.RehearsalMark.font-family = #'typewriter
1474 \mark \markup "Ouverture"
1475 \override Voice.TextScript.font-shape = #'italic
1476 \override Voice.TextScript.font-series = #'bold
1477 d''2.^\markup "Allegro"
1478 \override Voice.TextScript.font-size = #-3
1483 A similar syntax may be used in markup mode; however in this case it
1484 is preferable to use the simpler syntax explained in
1485 @ref{Selecting font and font size}:
1487 @lilypond[quote,verbatim]
1491 \override #'(font-shape . italic)
1492 \override #'(font-size . 4)
1496 \override #'(font-family . typewriter)
1498 \override #'(font-series . bold)
1502 \override #'(font-family . sans)
1509 Although it is easy to switch between preconfigured fonts, it is also
1510 possible to use other fonts, as explained in the following sections:
1511 @ref{Single entry fonts} and @ref{Entire document fonts}.
1515 @ref{The Feta font},
1516 @ref{Music notation inside markup},
1517 @ref{Rotating objects},
1518 @ref{Selecting font and font size},
1522 @node Single entry fonts
1523 @unnumberedsubsubsec Single entry fonts
1525 Any font that is installed on the operating system and recognized by
1526 FontConfig may be used in a score, using the following syntax:
1528 @lilypond[quote,verbatim,fragment]
1529 \override Staff.TimeSignature.font-name = #"Bitstream Charter"
1530 \override Staff.TimeSignature.font-size = #2
1534 \override #'(font-name . "Vera Bold")
1539 @cindex fonts, finding available
1540 @cindex finding available fonts
1541 @cindex listing available fonts
1542 @cindex available fonts, listing
1544 @funindex show-available-fonts
1546 Running lilypond with the following option displays a list of all
1547 available fonts on the operating system:
1550 lilypond -dshow-available-fonts x
1555 @ref{Fonts explained},
1556 @ref{Entire document fonts}.
1561 @c A source file gets never installed...
1563 @c @file{lily/font-config-scheme.cc}.
1566 @node Entire document fonts
1567 @unnumberedsubsubsec Entire document fonts
1569 It is possible to change the fonts to be used as the default fonts in
1570 the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
1571 specifying them, in that order, as shown in the example below, which
1572 automatically scales the fonts with the value set for the global staff
1573 size. For an explanation of fonts, see @ref{Fonts explained}.
1575 @cindex font families, setting
1576 @cindex fonts, changing for entire document
1578 @funindex make-pango-font-tree
1580 @lilypond[verbatim,quote]
1583 (make-pango-font-tree "Times New Roman"
1586 (/ staff-height pt 20)))
1593 \typewriter typewriter. }
1597 @c we don't do Helvetica / Courier, since GS incorrectly loads
1602 @ref{Fonts explained},
1603 @ref{Single entry fonts},
1604 @ref{Selecting font and font size},