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,relative=2]
63 a8^"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,relative=2]
71 a8^\markup { \italic pizz. } g f e
72 a4_\markup { \tiny scherz. \bold molto } f
75 By default, text indications do not influence the note spacing. However,
76 their widths can be taken into account: in the following example, the
77 first text string does not affect spacing, whereas the second one does.
79 @lilypond[quote,verbatim,relative=2]
85 In addition to text scripts, articulations can be attached to notes.
86 For more information, see @ref{Articulations and ornamentations}.
88 For more information about the relative ordering of text scripts and
89 articulations, see @rlearning{Placement of objects}.
91 @funindex \textLengthOn
92 @funindex textLengthOn
93 @funindex \textLengthOff
94 @funindex textLengthOff
98 @code{\textLengthOff}.
103 @rlearning{Placement of objects}.
106 @ref{Formatting text},
107 @ref{Direction and placement},
108 @ref{Articulations and ornamentations}.
114 @rinternals{TextScript}.
116 @cindex text outside margin
117 @cindex margin, text running over
118 @cindex text, keeping inside margin
119 @cindex lyrics, keeping inside margin
122 Checking to make sure that text scripts and lyrics are within the
123 margins requires additonal calculations. In cases where slightly faster
124 performance is desired, use
127 \override Score.PaperColumn #'keep-inside-line = ##f
132 @unnumberedsubsubsec Text spanners
134 @cindex text spanners
136 Some performance indications, e.g., @notation{rallentando} or
137 @notation{accelerando}, are written as text and are extended over
138 multiple notes with dotted lines. Such objects, called
139 @qq{spanners}, may be created from one note to another using the
142 @lilypond[verbatim,quote,relative=2]
143 \override TextSpanner #'(bound-details left text) = "rit."
148 @cindex text spanners, formatting
149 @cindex formatting text spanners
152 The string to be printed is set through object properties. By default
153 it is printed in italic characters, but different formatting can be
154 obtained using @code{\markup} blocks, as described in
155 @ref{Formatting text}.
157 @lilypond[quote,relative=2,verbatim]
158 \override TextSpanner #'(bound-details left text) =
159 \markup { \upright "rit." }
164 The line style, as well as the text string, can be defined as an
165 object property. This syntax is described in @ref{Line styles}.
167 @funindex \textSpannerUp
168 @funindex textSpannerUp
169 @funindex \textSpannerDown
170 @funindex textSpannerDown
171 @funindex \textSpannerNeutral
172 @funindex textSpannerNeutral
176 @code{\textSpannerUp},
177 @code{\textSpannerDown},
178 @code{\textSpannerNeutral}.
182 LilyPond is only able to handle one text spanner per voice.
186 @lilypondfile[verbatim,quote,texidoc,doctitle]
187 {dynamics-text-spanner-postfix.ly}
189 @lilypondfile[verbatim,quote,texidoc,doctitle]
190 {dynamics-custom-text-spanner-postfix.ly}
196 @ref{Formatting text}.
200 @rlsr{Expressive marks}.
203 @rinternals{TextSpanner}.
207 @unnumberedsubsubsec Text marks
212 @cindex text on bar line
213 @cindex coda on bar line
214 @cindex segno on bar line
215 @cindex fermata on bar line
216 @cindex bar lines, symbols on
223 Various text elements may be added to a score using the syntax described
224 in @ref{Rehearsal marks}:
226 @c \mark needs to be placed on a separate line (it's not
227 @c attached to an object like \markup is). -vv
229 @lilypond[verbatim,quote,relative=2]
235 This syntax makes it possible to put any text on a bar line;
236 more complex text formatting may be added using a @code{\markup}
237 block, as described in @ref{Formatting text}:
239 @lilypond[quote,verbatim,relative=1]
241 \mark \markup { \italic { colla parte } }
247 This syntax also allows to print special signs, like coda, segno
248 or fermata, by specifying the appropriate symbol name as explained in
249 @ref{Music notation inside markup}:
251 @lilypond[quote,verbatim,relative=2]
253 \mark \markup { \musicglyph #"scripts.ufermata" }
258 Such objects are only typeset above the top staff of the score;
259 depending on whether they are specified at the end or the middle of a
260 bar, they can be placed above the bar line or between notes. When
261 specified at a line break, the mark will be printed at the beginning of
264 @lilypond[quote,verbatim,relative=2]
274 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
275 {printing-marks-at-the-end-of-a-line.ly}
277 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
278 {aligning-marks-with-various-notation-objects.ly}
280 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
281 {printing-marks-on-every-staff.ly}
285 @ref{Rehearsal marks},
286 @ref{Formatting text},
287 @ref{Music notation inside markup},
294 @rinternals{MarkEvent},
295 @rinternals{Mark_engraver},
296 @rinternals{RehearsalMark}.
300 @unnumberedsubsubsec Separate text
302 @cindex separate text
303 @cindex text, separate
304 @cindex standalone text
305 @cindex top-level text
306 @cindex text, top-level
307 @cindex text, standalone
312 A @code{\markup} block can exist by itself, outside of any
313 @code{\score} block, as a @qq{top-level expression}. This syntax
314 is described in @ref{File structure}.
316 @lilypond[verbatim,quote]
318 Tomorrow, and tomorrow, and tomorrow...
323 This allows printing text separately from the music, which is
324 particularly useful when the input file contains several music pieces,
325 as described in @ref{Multiple scores in a book}.
327 @lilypond[quote,verbatim]
332 Tomorrow, and tomorrow, and tomorrow...
339 Separate text blocks can be spread over multiple pages,
340 making it possible to print text documents or books entirely
341 within LilyPond. This feature, and the specific syntax it
342 requires, are described in @ref{Multi-page markup}.
347 @funindex \markuplist
358 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
359 {stand-alone-two-column-markup.ly}
363 @ref{Formatting text},
364 @ref{File structure},
365 @ref{Multiple scores in a book},
366 @ref{Multi-page markup}.
372 @rinternals{TextScript}.
375 @node Formatting text
376 @subsection Formatting text
378 This section presents basic and advanced text formatting,
379 using the @code{\markup} mode specific syntax.
382 * Text markup introduction::
383 * Selecting font and font size::
385 * Graphic notation inside markup::
386 * Music notation inside markup::
387 * Multi-page markup::
390 @node Text markup introduction
391 @unnumberedsubsubsec Text markup introduction
401 A @code{\markup} block is used to typeset text with an extensible
402 syntax called @qq{markup mode}.
404 @cindex markup expressions
405 @cindex expressions, markup
406 @cindex markup syntax
407 @cindex syntax, markup
409 The markup syntax is similar to LilyPond's usual syntax: a
410 @code{\markup} expression is enclosed in curly braces
411 @code{@{@dots{} @}}. A single word is regarded as a minimal expression,
412 and therefore does not need to be enclosed with braces.
414 Unlike simple @qq{quoted text} indications, @code{\markup} blocks may
415 contain nested expressions or markup commands, entered using the
416 backslash @code{\} character. Such commands only affect the first
417 following expression.
419 @lilypond[quote,verbatim,relative=2]
421 a2^\markup { poco \italic più forte }
423 d2_\markup { \italic "string. assai" }
425 b1^\markup { \bold { molto \italic agitato } }
429 @cindex special characters in markup mode
430 @cindex markup mode, special characters
431 @cindex reserved characters, printing
432 @cindex printing reserved characters
433 @cindex printing special characters
434 @cindex quoted text in markup mode
435 @cindex markup mode, quoted text
437 A @code{\markup} block may also contain quoted text strings. Such
438 strings are treated as minimal text expressions, and therefore any
439 markup command or special character (such as @code{\} and@tie{}@code{#})
440 will be printed verbatim without affecting the formatting of the text.
441 Double quotation marks themselves may be printed by preceding them
444 @lilypond[quote,verbatim,relative=2]
445 a1^"\italic markup..."
446 a_\markup { \italic "... prints \"italic\" letters!" }
450 To be treated as a distinct expression, a list of words needs to be
451 enclosed with double quotes or preceded by a command. The way markup
452 expressions are defined affects how these expressions will be stacked,
453 centered and aligned; in the following example, the second
454 @code{\markup} expression is treated the same as the first one:
456 @lilypond[quote,verbatim,relative=2]
457 c1^\markup { \center-column { a bbb c } }
458 c1^\markup { \center-column { a { bbb c } } }
459 c1^\markup { \center-column { a \line { bbb c } } }
460 c1^\markup { \center-column { a "bbb c" } }
463 Markups can be stored in variables. Such variables may be
464 directly attached to notes:
466 @lilypond[quote,verbatim]
467 allegro = \markup { \bold \large Allegro }
477 An exhaustive list of @code{\markup}-specific commands can be found in
478 @ref{Text markup commands}.
482 @ref{Text markup commands}.
488 @file{scm/markup.scm}.
491 Syntax errors for markup mode can be confusing.
494 @node Selecting font and font size
495 @unnumberedsubsubsec Selecting font and font size
497 @cindex font switching
498 @cindex changing fonts
499 @cindex switching fonts
508 Basic font switching is supported in markup mode:
510 @lilypond[quote,verbatim,relative=2]
513 \italic { non troppo \underline Vivo }
516 d,_\markup { \italic quasi \smallCaps Tromba }
532 The size of the characters can also be altered in different ways:
535 the font size can be set to predefined standard sizes,
538 the font size can be set to an absolute value,
541 the font size can also be changed relatively to its previous value.
545 The following example demonstrates these three methods:
547 @lilypond[quote,verbatim,relative=1]
554 \fontsize #5 Sinfonia
561 \magnify #0.6 { e sentimento } )
574 Text may be printed as subscript or superscript. By default these are
575 printed in a smaller size, but a normal size can be used as well:
577 @lilypond[quote,verbatim]
580 \line { 1 \super st movement }
581 \line { 1 \normal-size-super st movement
582 \sub { (part two) } }
587 @cindex font families
589 The markup mode provides an easy way to select alternate font
590 families. The default serif font, of roman type, is automatically
591 selected unless specified otherwise; on the last line of the following
592 example, there is no difference between the first and the second word.
594 @lilypond[quote,verbatim]
597 \line { Act \number 1 }
598 \line { \sans { Scene I. } }
599 \line { \typewriter { Verona. An open place. } }
600 \line { Enter \roman Valentine and Proteus. }
606 Some of these font families, used for specific items such as numbers
607 or dynamics, do not provide all characters, as mentioned in
608 @ref{New dynamic marks} and @ref{Manual repeat marks}.
610 @c \concat is actually documented in Align (it is not
611 @c a font-switching command). But we need it here. -vv
613 When used inside a word, some font-switching or formatting commands
614 may produce an unwanted blank space. This can easily be solved by
615 concatenating the text elements together:
617 @lilypond[quote,verbatim]
621 \concat { 1 \super st }
625 \concat { \dynamic p , }
626 \italic { con dolce espressione }
632 An exhaustive list of font switching commands and custom font usage
633 commands can be found in @ref{Font}.
635 Defining custom font sets is also possible, as explained in
644 @funindex \normalsize
670 @ref{New dynamic marks},
671 @ref{Manual repeat marks},
675 @file{scm/define-markup-commands.scm}.
681 @rinternals{TextScript}.
684 Using the font sizing commands @code{\teeny}, @code{\tiny},
685 @code{\small}, @code{\normalsize}, @code{\large}, and
686 @code{\huge} will lead to inconsistent line spacing compared to
687 using @code{\fontsize}.
691 @unnumberedsubsubsec Text alignment
693 @cindex text, aligning
694 @cindex aligning text
695 @cindex aligning markup text
696 @cindex aligning markups
697 @cindex markups, aligning
698 @cindex markup text, aligning
700 This subsection discusses how to place text in markup mode. Markup
701 objects can also be moved as a whole, using the syntax described in
702 @rlearning{Moving objects}.
704 @c Padding commands should be mentioned on this page, but
705 @c most of these require \box to be more clearly illustrated. -vv
707 @cindex text, horizontal alignment
708 @cindex horizontal text alignment
710 @funindex \left-align
712 @funindex \center-align
713 @funindex center-align
714 @funindex \right-align
715 @funindex right-align
717 Markup objects may be aligned in different ways. By default, a text
718 indication is aligned on its left edge: in the following example,
719 there is no difference between the first and the second markup.
721 @lilypond[quote,verbatim,relative=2]
724 d-\markup { \left-align poco }
726 d-\markup { \center-align { poco } }
728 d-\markup { \right-align poco }
734 Horizontal alignment may be fine-tuned using a numeric value:
736 @lilypond[quote,verbatim,relative=2]
737 a1-\markup { \halign #-1 poco }
739 a,-\markup { \halign #0 poco }
741 a,-\markup { \halign #0.5 poco }
743 a,-\markup { \halign #2 poco }
747 Some objects may have alignment procedures of their own, and therefore
748 are not affected by these commands. It is possible to move such
749 markup objects as a whole, as shown for instance in
752 @cindex text, vertical alignment
753 @cindex vertical text alignment
762 @c QUERY Should the function of ``\null'' be clarified? rp
764 Vertical alignment is a bit more complex. As stated above, markup
765 objects can be moved as a whole; however, it is also possible to move
766 specific elements inside a markup block. In this case, the element to
767 be moved needs to be preceded with an @emph{anchor point}, that can be
768 another markup element or an invisible object. The following example
769 demonstrates these two possibilities; the last markup in this example
770 has no anchor point, and therefore is not moved.
772 @lilypond[quote,verbatim,relative=1]
775 \raise #2 { Scène 1 }
780 \lower #4 \bold { Très modéré }
784 \raise #4 \italic { Une forêt. }
789 @funindex \general-align
790 @funindex general-align
793 @funindex \translate-scaled
794 @funindex translate-scaled
796 Some commands can affect both the horizontal and vertical alignment of
797 text objects in markup mode. Any object affected by these commands
798 must be preceded with an anchor point:
800 @lilypond[quote,verbatim,relative=1]
803 \translate #'(-1 . 2) "Scène 1"
808 \general-align #Y #3.2 \bold "Très modéré"
813 \translate-scaled #'(-1 . 2) \teeny "Une forêt."
818 @cindex multi-line markup
819 @cindex markup, multi-line
820 @cindex multi-line text
821 @cindex text, multi-line
822 @cindex text in columns
823 @cindex columns, text
827 @funindex \center-column
828 @funindex center-column
830 A markup object may include several lines of text. In the following
831 example, each element or expression is placed on its own line, either
832 left-aligned or centered:
834 @lilypond[quote,verbatim]
850 @cindex centering text on the page
851 @cindex text, centering on the page
852 @cindex markup, centering on the page
857 Similarly, a list of elements or expressions may be spread to fill the
858 entire horizontal line width (if there is only one element, it will be
859 centered on the page). These expressions can, in turn, include
860 multi-line text or any other markup expression:
862 @lilypond[quote,verbatim]
865 \line { William S. Gilbert }
867 \huge \smallCaps "The Mikado"
869 \smallCaps "The Town of Titipu"
871 \line { Sir Arthur Sullivan }
879 @cindex wordwrapped text
880 @cindex justified text
881 @cindex text, justified
882 @cindex text, wordwrapped
883 @cindex markup text, wordwrapped
884 @cindex markup text, justified
891 Long text indications can also be automatically wrapped accordingly to
892 the given line width. These will be either left-aligned or justified,
893 as shown in the following example.
895 @lilypond[quote,verbatim]
898 \line \smallCaps { La vida breve }
899 \line \bold { Acto I }
901 (La escena representa el corral de una casa de
902 gitanos en el AlbaicÃn de Granada. Al fondo una
903 puerta por la que se ve el negro interior de
904 una Fragua, iluminado por los rojos resplandores
909 \line \bold { Acto II }
910 \override #'(line-width . 50)
912 (Calle de Granada. Fachada de la casa de Carmela
913 y su hermano Manuel con grandes ventanas abiertas
914 a través de las que se ve el patio
915 donde se celebra una alegre fiesta)
921 @cindex text alignment commands
922 @cindex markup text alignment commands
923 @cindex alignment, text, commands
925 An exhaustive list of text alignment commands can be found in
930 @rlearning{Moving objects}.
937 @file{scm/define-markup-commands.scm}.
943 @rinternals{TextScript}.
946 @node Graphic notation inside markup
947 @unnumberedsubsubsec Graphic notation inside markup
949 @cindex graphics, embedding
950 @cindex drawing graphic objects
951 @cindex graphic objects, drawing
952 @cindex embedding graphic objects
953 @cindex graphic objects, embedding
955 Various graphic objects may be added to a score, using markup
958 @cindex decorating text
960 @cindex text, framing
961 @cindex text, decorating
962 @cindex markup text, decorating
963 @cindex markup text, framing
969 @funindex \rounded-box
970 @funindex rounded-box
976 Some markup commands allow decoration of text elements with graphics,
977 as demonstrated in the following example.
979 @lilypond[quote,verbatim]
988 \bracket "1866 - 1925"
991 \rounded-box \bold Prelude
996 @cindex padding around text
998 @cindex markup text padding
1000 @funindex \pad-markup
1001 @funindex pad-markup
1004 @funindex \pad-to-box
1005 @funindex pad-to-box
1006 @funindex \pad-around
1007 @funindex pad-around
1009 Some commands may require an increase in the padding around the text;
1010 this is achieved with some markup commands exhaustively described in
1013 @lilypond[quote,verbatim]
1014 \markup \fill-line {
1016 \box "Charles Ives (1874 - 1954)"
1018 \box \pad-markup #2 "THE UNANSWERED QUESTION"
1019 \box \pad-x #8 "A Cosmic Landscape"
1026 \box \pad-to-box #'(-5 . 20) #'(0 . 5)
1027 \bold "Largo to Presto"
1030 "String quartet keeps very even time,
1031 Flute quartet keeps very uneven time."
1035 @cindex graphic notation
1036 @cindex symbols, non-musical
1037 @cindex non-musical symbols
1038 @cindex notation, graphic
1042 @funindex \draw-circle
1043 @funindex draw-circle
1044 @funindex \filled-box
1045 @funindex filled-box
1048 @funindex \draw-line
1050 @funindex \arrow-head
1051 @funindex arrow-head
1053 Other graphic elements or symbols may be printed without requiring any
1054 text. As with any markup expression, such objects can be combined.
1056 @lilypond[quote,verbatim]
1059 \draw-circle #4 #0.4 ##f
1060 \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
1066 \draw-line #'(0 . 4)
1067 \arrow-head #Y #DOWN ##f
1072 @cindex embedded graphics
1073 @cindex images, embedding
1074 @cindex graphics, embedding
1079 @funindex \postscript
1080 @funindex postscript
1082 Advanced graphic features include the ability to include external
1083 image files converted to the Encapsulated PostScript format
1084 (@emph{eps}), or to directly embed graphics into the input file, using
1085 native PostScript code. In such a case, it may be useful to
1086 explicitly specify the size of the drawing, as demonstrated below:
1088 @lilypond[quote,verbatim,relative=1]
1091 \epsfile #X #10 #"./context-example.eps"
1092 \with-dimensions #'(0 . 6) #'(0 . 10)
1108 An exhaustive list of graphics-specific commands can be found in
1114 @ref{Editorial annotations},
1118 @file{scm/define-markup-commands.scm},
1119 @file{scm/stencil.scm}.
1124 Internals Reference:
1125 @rinternals{TextScript}.
1128 @node Music notation inside markup
1129 @unnumberedsubsubsec Music notation inside markup
1131 @cindex notation inside markup
1132 @cindex music inside markup
1133 @cindex markup, music notation inside
1135 Various musical notation elements may be added to a score, inside a
1138 Notes and accidentals can be entered using markup commands:
1140 @lilypond[quote,verbatim,relative=2]
1144 \note-by-number #1 #1 #1.5
1147 \natural \semiflat \flat
1148 \sesquiflat \doubleflat
1152 \natural \semisharp \sharp
1153 \sesquisharp \doublesharp
1158 Other notation objects may also be printed
1161 @lilypond[quote,verbatim,relative=1]
1168 fis_\markup { \dynamic rf }
1179 More generally, any available musical symbol may be included
1180 separately in a markup object, as demonstrated below; an exhaustive
1181 list of these symbols and their names can be found in
1182 @ref{The Feta font}.
1184 @lilypond[quote,verbatim,relative=2]
1186 c'^\markup { \musicglyph #"eight" }
1188 c,8._\markup { \musicglyph #"clefs.G_change" }
1190 c2^\markup { \musicglyph #"timesig.neomensural94" }
1193 Another way of printing non-text glyphs is described in
1194 @ref{Fonts explained}. This is useful for printing braces of various
1197 The markup mode also supports diagrams for specific
1200 @lilypond[quote,verbatim,relative=2]
1202 \fret-diagram-terse #"x;x;o;2;3;2;"
1205 \harp-pedal #"^-v|--ov^"
1210 \musicglyph #"accordion.discant"
1212 \raise #0.5 \musicglyph #"accordion.dot"
1213 \raise #1.5 \musicglyph #"accordion.dot"
1217 @c The accordion diagram is actually taken from a snippet.
1220 Such diagrams are documented in @ref{Instrument Specific Markup}.
1222 @cindex score inside markup
1223 @cindex markup, score inside
1225 A whole score can even be nested inside a markup object. In such a
1226 case, the nested @code{\score} block must contain a @code{\layout}
1227 block, as demonstrated here:
1229 @lilypond[quote,verbatim,relative=1]
1232 \relative c' { c4 d e f }
1240 An exhaustive list of music notation related commands can be found in
1246 @ref{The Feta font},
1247 @ref{Fonts explained}.
1250 @file{scm/define-markup-commands.scm},
1251 @file{scm/fret-diagrams.scm},
1252 @file{scm/harp-pedals.scm}.
1257 Internals Reference:
1258 @rinternals{TextScript}.
1261 @node Multi-page markup
1262 @unnumberedsubsubsec Multi-page markup
1264 @cindex multi-page markup
1265 @cindex markup, multi-page
1266 @cindex markup text, multi-page
1267 @cindex text spread over multiple pages
1269 @funindex \markuplist
1270 @funindex markuplist
1271 @funindex \justified-lines
1272 @funindex justified-lines
1273 @funindex \wordwrap-lines
1274 @funindex wordwrap-lines
1276 Although standard markup objects are not breakable, a specific syntax
1277 makes it possible to enter lines of text that can spread over multiple
1280 @lilypond[quote,verbatim]
1283 A very long text of justified lines.
1287 Another very long paragraph.
1294 This syntax accepts a list of markups, that can be
1297 the result of a markup list command,
1301 a list of markup lists.
1304 An exhaustive list of markup list commands can be found in
1305 @ref{Text markup list commands}.
1309 @ref{Text markup list commands}.
1312 @rextend{New markup list command definition}.
1315 @file{scm/define-markup-commands.scm}.
1320 Internals Reference:
1321 @rinternals{TextScript}.
1323 @funindex \markuplist
1324 @funindex markuplist
1334 This section presents the way fonts are handled, and how they may be
1339 * Single entry fonts::
1340 * Entire document fonts::
1343 @node Fonts explained
1344 @unnumberedsubsubsec Fonts explained
1347 @cindex fonts, explained
1348 @cindex braces, various sizes
1349 @cindex fonts, non-text in markup
1350 @cindex non-text fonts in markup
1352 @funindex font-interface
1354 Fonts are handled through several libraries. FontConfig is used to
1355 detect available fonts on the system; the selected fonts are rendered
1358 Music notation fonts can be described as a set of specific glyphs,
1359 ordered in several families. The following syntax allows various
1360 LilyPond @code{feta} non-text fonts to be used directly in markup
1363 @lilypond[quote,verbatim,relative=2]
1366 \override #'(font-encoding . fetaBraces)
1368 \override #'(font-encoding . fetaText)
1370 \override #'(font-encoding . fetaMusic)
1371 \lookup #"noteheads.s0petrucci"
1377 However, all these glyphs except the braces of various sizes contained
1378 in @code{fetaBraces} are available using the simpler syntax described
1379 in @ref{Music notation inside markup}.
1381 When using the glyphs contained in @code{fetaBraces}, the size of the
1382 brace is specified by the numerical part of the glyph name, in
1383 arbitrary units. Any integer from @code{0} to @code{575} inclusive
1384 may be specified, @code{0} giving the smallest brace. The optimum
1385 value must be determined by trial and error. These glyphs are all
1386 left braces; right braces may be obtained by rotation, see
1387 @ref{Rotating objects}.
1389 Three families of text fonts are made available: the @emph{roman}
1390 (serif) font, that defaults to New Century Schoolbook, the
1391 @emph{sans} font and the monospaced @emph{typewriter} font -- these
1392 last two families are determined by the Pango installation.
1394 Each family may include different shapes and series. The following
1395 example demonstrates the ability to select alternate families, shapes,
1396 series and sizes. The value supplied to @code{font-size} is the
1397 required change from the default size.
1399 @lilypond[quote,verbatim,relative=2]
1400 \override Score.RehearsalMark #'font-family = #'typewriter
1401 \mark \markup "Ouverture"
1402 \override Voice.TextScript #'font-shape = #'italic
1403 \override Voice.TextScript #'font-series = #'bold
1404 d2.^\markup "Allegro"
1405 \override Voice.TextScript #'font-size = #-3
1410 A similar syntax may be used in markup mode; however in this case it
1411 is preferable to use the simpler syntax explained in
1412 @ref{Selecting font and font size}:
1414 @lilypond[quote,verbatim]
1418 \override #'(font-shape . italic)
1419 \override #'(font-size . 4)
1423 \override #'(font-family . typewriter)
1425 \override #'(font-series . bold)
1429 \override #'(font-family . sans)
1436 Although it is easy to switch between preconfigured fonts, it is also
1437 possible to use other fonts, as explained in the following sections:
1438 @ref{Single entry fonts} and @ref{Entire document fonts}.
1442 @ref{The Feta font},
1443 @ref{Music notation inside markup},
1444 @ref{Rotating objects},
1445 @ref{Selecting font and font size},
1449 @node Single entry fonts
1450 @unnumberedsubsubsec Single entry fonts
1452 Any font that is installed on the operating system and recognized by
1453 FontConfig may be used in a score, using the following syntax:
1455 @lilypond[quote,verbatim,relative=2]
1456 \override Staff.TimeSignature #'font-name = #"Bitstream Charter"
1457 \override Staff.TimeSignature #'font-size = #2
1461 \override #'(font-name . "Vera Bold")
1466 @cindex fonts, finding available
1467 @cindex finding available fonts
1468 @cindex listing available fonts
1469 @cindex available fonts, listing
1471 @funindex show-available-fonts
1473 The following command displays a list of all available fonts on the
1477 lilypond -dshow-available-fonts x
1482 @ref{Fonts explained},
1483 @ref{Entire document fonts}.
1488 @c A source file gets never installed...
1490 @c @file{lily/font-config-scheme.cc}.
1493 @node Entire document fonts
1494 @unnumberedsubsubsec Entire document fonts
1496 It is possible to change the fonts to be used as the default fonts in
1497 the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
1498 specifying them, in that order, as shown in the example below. For an
1499 explanation of fonts, see @ref{Fonts explained}.
1501 @cindex font families, setting
1502 @cindex fonts, changing for entire document
1504 @funindex make-pango-font-tree
1506 @lilypond[verbatim,quote]
1510 (make-pango-font-tree "Times New Roman"
1513 (/ myStaffSize 20)))
1520 \typewriter typewriter. }
1524 @c we don't do Helvetica / Courier, since GS incorrectly loads
1529 @ref{Fonts explained},
1530 @ref{Single entry fonts},
1531 @ref{Selecting font and font size},