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
67 formatting may be added to a note by explicitly using a
68 @code{\markup} block, as described 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.
76 However, their widths can be taken into account:
77 in the following example, the first text string does not affect
78 spacing, whereas the second one does.
80 @lilypond[quote,verbatim,relative=2]
86 In addition to text scripts, articulations can be attached to notes.
87 For more information, see @ref{Articulations and ornamentations}.
89 For more information about the relative ordering of text scripts and
90 articulations, see @rlearning{Placement of objects}.
92 @funindex \textLengthOn
93 @funindex textLengthOn
94 @funindex \textLengthOff
95 @funindex textLengthOff
99 @code{\textLengthOff}.
105 @rlearning{Placement of objects}.
108 @ref{Formatting text},
109 @ref{Direction and placement}.
115 @rinternals{TextScript}.
118 @cindex text outside margin
119 @cindex margin, text running over
120 @cindex text, keeping inside margin
121 @cindex lyrics, keeping inside margin
126 Checking to make sure that text scripts and lyrics are within the
127 margins is a relatively large computational task. To speed up
128 processing, LilyPond does not perform such calculations by
129 default; to enable it, use
132 \override Score.PaperColumn #'keep-inside-line = ##t
137 @unnumberedsubsubsec Text spanners
139 @cindex text spanners
141 Some performance indications, e.g., @notation{rallentando} or
142 @notation{accelerando}, are written as text and are extended over
143 multiple notes with dotted lines. Such objects, called @qq{spanners},
144 may be created from one note to another using the following syntax:
146 @lilypond[verbatim,quote,relative=2]
147 \override TextSpanner #'(bound-details left text) = "rit."
152 @cindex text spanners, formatting
153 @cindex formatting text spanners
156 The string to be printed is set through object properties. By default
157 it is printed in italic characters, but different formatting can be
158 obtained using @code{\markup} blocks, as described in
159 @ref{Formatting text}.
161 @lilypond[quote,relative=2,verbatim]
162 \override TextSpanner #'(bound-details left text) =
163 \markup { \upright "rit." }
168 The line style, as well as the text string, can be defined as an
169 object property. This syntax is described in @ref{Line styles}.
170 Text spanners are part of the @code{Dynamics} context; see
171 @rinternals{Dynamics}.
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,lilyquote,texidoc,doctitle]
194 {dynamics-text-spanner-postfix.ly}
196 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
197 {dynamics-custom-text-spanner-postfix.ly}
206 @rlsr{Expressive marks}.
209 @rinternals{TextSpanner},
210 @rinternals{Dynamics}.
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
231 the syntax described 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,relative=2]
242 This syntax makes it possible to put any text on a bar line;
243 more complex text formatting may be added using a @code{\markup}
244 block, as described in @ref{Formatting text}:
246 @lilypond[quote,verbatim,relative=1]
248 \mark \markup { \italic { colla parte } }
254 This syntax also allows to print special signs, like coda, segno
255 or fermata, by specifying the appropriate symbol name as explained in
256 @ref{Music notation inside markup}:
258 @lilypond[quote,verbatim,relative=2]
260 \mark \markup { \musicglyph #"scripts.ufermata" }
265 Such objects are only typeset above the top staff of the score; depending on
266 whether they are specified at the end or the middle of a bar, they
267 can be placed above the bar line or between notes. When specified at a
268 line break, the mark will be printed at the beginning of the next line.
270 @lilypond[quote,verbatim,relative=2]
280 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
281 {printing-marks-at-the-end-of-a-line.ly}
283 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
284 {aligning-marks-with-various-notation-objects.ly}
286 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
287 {printing-marks-on-every-staff.ly}
292 @ref{Rehearsal marks},
293 @ref{Formatting text},
294 @ref{Music notation inside markup},
301 @rinternals{MarkEvent},
302 @rinternals{Mark_engraver},
303 @rinternals{RehearsalMark}.
307 @unnumberedsubsubsec Separate text
309 @cindex separate text
310 @cindex text, separate
311 @cindex standalone text
312 @cindex top-level text
313 @cindex text, top-level
314 @cindex text, standalone
319 A @code{\markup} block can exist by itself, outside of any
320 @code{\score} block, as a @qq{top-level expression}. This syntax
321 is described in @ref{File structure}.
323 @lilypond[verbatim,quote]
325 Tomorrow, and tomorrow, and tomorrow...
330 This allows printing text separately from the music, which is
331 particularly useful when the input file contains several music pieces,
332 as described in @ref{Multiple scores in a book}.
334 @lilypond[quote,verbatim]
339 Tomorrow, and tomorrow, and tomorrow...
346 Separate text blocks can be spread over multiple pages,
347 making it possible to print text documents or books entirely
348 within LilyPond. This feature, and the specific syntax it
349 requires, are described in @ref{Multi-page markup}.
354 @funindex \markuplines
355 @funindex markuplines
365 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
366 {stand-alone-two-column-markup.ly}
371 @ref{Formatting text},
372 @ref{File structure},
373 @ref{Multiple scores in a book},
374 @ref{Multi-page markup}.
380 @rinternals{TextScript}.
383 @node Formatting text
384 @subsection Formatting text
386 This section presents basic and advanced text formatting,
387 using the @code{\markup} mode specific syntax.
390 * Text markup introduction::
391 * Selecting font and font size::
393 * Graphic notation inside markup::
394 * Music notation inside markup::
395 * Multi-page markup::
398 @node Text markup introduction
399 @unnumberedsubsubsec Text markup introduction
409 A @code{\markup} block is used to typeset text with an extensible
410 syntax called @qq{markup mode}.
412 @cindex markup expressions
413 @cindex expressions, markup
414 @cindex markup syntax
415 @cindex syntax, markup
417 The markup syntax is similar to LilyPond's usual syntax: a
418 @code{\markup} expression is enclosed in curly braces @code{@{
419 @dots{} @}}. A single word is regarded as a minimal expression,
420 and therefore does not need to be enclosed with braces.
422 Unlike simple @qq{quoted text} indications, @code{\markup} blocks may
423 contain nested expressions or markup commands, entered using the
424 backslash @code{\} character. Such commands only affect the first
425 following expression.
427 @lilypond[quote,verbatim,relative=2]
429 a2^\markup { poco \italic più forte }
431 d2_\markup { \italic "string. assai" }
433 b1^\markup { \bold { molto \italic agitato } }
437 @cindex special characters in markup mode
438 @cindex markup mode, special characters
439 @cindex reserved characters, printing
440 @cindex printing reserved characters
441 @cindex printing special characters
442 @cindex quoted text in markup mode
443 @cindex markup mode, quoted text
445 A @code{\markup} block may also contain quoted text strings. Such
446 strings are treated as minimal text expressions, and therefore any
447 markup command or special character (such as @code{\} and @code{#})
448 will be printed verbatim without affecting the formatting of the text.
449 Double quotation marks themselves may be printed by preceding them
452 @lilypond[quote,verbatim,relative=2]
453 a1^"\italic markup..."
454 a_\markup { \italic "... prints \"italic\" letters!" }
458 To be treated as a distinct expression, a list of words needs to be
459 enclosed with double quotes or preceded by a command. The way markup
460 expressions are defined affects how these expressions will be stacked,
461 centered and aligned; in the following example, the second
462 @code{\markup} expression is treated the same as the first one:
464 @lilypond[quote,verbatim,relative=2]
465 c1^\markup { \center-column { a bbb c } }
466 c1^\markup { \center-column { a { bbb c } } }
467 c1^\markup { \center-column { a \line { bbb c } } }
468 c1^\markup { \center-column { a "bbb c" } }
471 Markups can be stored in variables. Such variables may be
472 directly attached to notes:
474 @lilypond[quote,verbatim]
475 allegro = \markup { \bold \large Allegro }
485 An exhaustive list of @code{\markup}-specific commands can be found in
486 @ref{Text markup commands}.
491 @ref{Text markup commands}.
497 @file{scm/markup.scm}.
502 Syntax errors for markup mode can be confusing.
505 @node Selecting font and font size
506 @unnumberedsubsubsec Selecting font and font size
508 @cindex font switching
509 @cindex changing fonts
510 @cindex switching fonts
519 Basic font switching is supported in markup mode:
521 @lilypond[quote,verbatim,relative=2]
524 \italic { non troppo \underline Vivo }
527 d,_\markup { \italic quasi \smallCaps Tromba }
543 The size of the characters can also be altered in different ways:
546 the font size can be set to predefined standard sizes,
549 the font size can be set to an absolute value,
552 the font size can also be changed relatively to its previous value.
556 The following example demonstrates these three methods:
558 @lilypond[quote,verbatim,relative=1]
565 \fontsize #5 Sinfonia
572 \magnify #0.6 { e sentimento } )
585 Text may be printed as subscript or superscript. By default these are
586 printed in a smaller size, but a normal size can be used as well:
588 @lilypond[quote,verbatim]
591 \line { 1 \super st movement }
592 \line { 1 \normal-size-super st movement
593 \sub { (part two) } }
598 @cindex font families
600 The markup mode provides an easy way to select alternate font
601 families. The default serif font, of roman type, is automatically
602 selected unless specified otherwise; on the last line of the following
603 example, there is no difference between the first and the second word.
605 @lilypond[quote,verbatim]
608 \line { Act \number 1 }
609 \line { \sans { Scene I. } }
610 \line { \typewriter { Verona. An open place. } }
611 \line { Enter \roman Valentine and Proteus. }
617 Some of these font families, used for specific items such as numbers
618 or dynamics, do not provide all characters, as mentioned in
619 @ref{New dynamic marks} and @ref{Manual repeat marks}.
621 @c \concat is actually documented in Align (it is not
622 @c a font-switching command). But we need it here. -vv
624 When used inside a word, some font-switching or formatting commands
625 may produce an unwanted blank space. This can easily be solved by
626 concatenating the text elements together:
628 @lilypond[quote,verbatim]
632 \concat { 1 \super st }
636 \concat { \dynamic p , }
637 \italic { con dolce espressione }
643 An exhaustive list of font switching commands and custom font usage
644 commands can be found in @ref{Font}.
646 Defining custom font sets is also possible, as explained in
655 @funindex \normalsize
682 @ref{New dynamic marks},
683 @ref{Manual repeat marks},
690 @rinternals{TextScript}.
693 @file{scm/define-markup-commands.scm}.
697 @unnumberedsubsubsec Text alignment
699 @cindex text, aligning
700 @cindex aligning text
701 @cindex aligning markup text
702 @cindex aligning markups
703 @cindex markups, aligning
704 @cindex markup text, aligning
706 This subsection discusses how to place text in markup mode. Markup
707 objects can also be moved as a whole, using the syntax described in
708 @rlearning{Moving objects}.
710 @c Padding commands should be mentioned on this page, but
711 @c most of these require \box to be more clearly illustrated. -vv
713 @cindex text, horizontal alignment
714 @cindex horizontal text alignment
716 @funindex \left-align
718 @funindex \center-align
719 @funindex center-align
720 @funindex \right-align
721 @funindex right-align
723 Markup objects may be aligned in different ways. By default, a text
724 indication is aligned on its left edge: in the following example,
725 there is no difference between the first and the second markup.
727 @lilypond[quote,verbatim,relative=2]
730 d-\markup { \left-align poco }
732 d-\markup { \center-align { poco } }
734 d-\markup { \right-align poco }
740 Horizontal alignment may be fine-tuned using a numeric value:
742 @lilypond[quote,verbatim,relative=2]
743 a1-\markup { \halign #-1 poco }
745 a,-\markup { \halign #0 poco }
747 a,-\markup { \halign #0.5 poco }
749 a,-\markup { \halign #2 poco }
753 Some objects may have alignment procedures of their own, and therefore
754 are not affected by these commands. It is possible to move such
755 markup objects as a whole, as shown for instance in @ref{Text marks}.
757 @cindex text, vertical alignment
758 @cindex vertical text alignment
767 @c QUERY Should the function of ``\null'' be clarified? rp
769 Vertical alignment is a bit more complex. As stated above, markup
770 objects can be moved as a whole; however, it is also possible to move
771 specific elements inside a markup block. In this case, the element to
772 be moved needs to be preceded with an @emph{anchor point}, that can be
773 another markup element or an invisible object. The following example
774 demonstrates these two possibilities; the last markup in this example
775 has no anchor point, and therefore is not moved.
777 @lilypond[quote,verbatim,relative=1]
780 \raise #2 { Scène 1 }
785 \lower #4 \bold { Très modéré }
789 \raise #4 \italic { Une forêt. }
794 @funindex \general-align
795 @funindex general-align
798 @funindex \translate-scaled
799 @funindex translate-scaled
801 Some commands can affect both the horizontal and vertical alignment of
802 text objects in markup mode. Any object affected by these commands
803 must be preceded with an anchor point:
805 @lilypond[quote,verbatim,relative=1]
808 \translate #'(-1 . 2) "Scène 1"
813 \general-align #Y #3.2 \bold "Très modéré"
818 \translate-scaled #'(-1 . 2) \teeny "Une forêt."
823 @cindex multi-line markup
824 @cindex markup, multi-line
825 @cindex multi-line text
826 @cindex text, multi-line
827 @cindex text in columns
828 @cindex columns, text
832 @funindex \center-column
833 @funindex center-column
835 A markup object may include several lines of text. In the following
836 example, each element or expression is placed on its own line, either
837 left-aligned or centered:
839 @lilypond[quote,verbatim]
855 @cindex centering text on the page
856 @cindex text, centering on the page
857 @cindex markup, centering on the page
862 Similarly, a list of elements or expressions may be spread to fill the
863 entire horizontal line width (if there is only one element, it will be
864 centered on the page). These expressions can, in turn, include
865 multi-line text or any other markup expression:
867 @lilypond[quote,verbatim]
870 \line { William S. Gilbert }
872 \huge \smallCaps "The Mikado"
874 \smallCaps "The Town of Titipu"
876 \line { Sir Arthur Sullivan }
884 @cindex wordwrapped text
885 @cindex justified text
886 @cindex text, justified
887 @cindex text, wordwrapped
888 @cindex markup text, wordwrapped
889 @cindex markup text, justified
896 Long text indications can also be automatically wrapped accordingly to
897 the given line width. These will be either left-aligned or justified,
898 as shown in the following example.
900 @lilypond[quote,verbatim]
903 \line \smallCaps { La vida breve }
904 \line \bold { Acto I }
906 (La escena representa el corral de una casa de
907 gitanos en el AlbaicÃn de Granada. Al fondo una
908 puerta por la que se ve el negro interior de
909 una Fragua, iluminado por los rojos resplandores
914 \line \bold { Acto II }
915 \override #'(line-width . 50)
917 (Calle de Granada. Fachada de la casa de Carmela
918 y su hermano Manuel con grandes ventanas abiertas
919 a través de las que se ve el patio
920 donde se celebra una alegre fiesta)
926 @cindex text alignment commands
927 @cindex markup text alignment commands
928 @cindex alignment, text, commands
930 An exhaustive list of text alignment commands can be found in
936 @rlearning{Moving objects}.
946 @rinternals{TextScript}.
949 @file{scm/define-markup-commands.scm}.
952 @node Graphic notation inside markup
953 @unnumberedsubsubsec Graphic notation inside markup
955 @cindex graphics, embedding
956 @cindex drawing graphic objects
957 @cindex graphic objects, drawing
958 @cindex embedding graphic objects
959 @cindex graphic objects, embedding
961 Various graphic objects may be added to a score, using markup
964 @cindex decorating text
966 @cindex text, framing
967 @cindex text, decorating
968 @cindex markup text, decorating
969 @cindex markup text, framing
975 @funindex \rounded-box
976 @funindex rounded-box
982 Some markup commands allow decoration of text elements with graphics,
983 as demonstrated in the following example.
985 @lilypond[quote,verbatim]
994 \bracket "1866 - 1925"
997 \rounded-box \bold Prelude
1002 @cindex padding around text
1003 @cindex text padding
1004 @cindex markup text padding
1006 @funindex \pad-markup
1007 @funindex pad-markup
1010 @funindex \pad-to-box
1011 @funindex pad-to-box
1012 @funindex \pad-around
1013 @funindex pad-around
1015 Some commands may require an increase in the padding around the text;
1016 this is achieved with some markup commands exhaustively described in
1019 @lilypond[quote,verbatim]
1020 \markup \fill-line {
1022 \box "Charles Ives (1874 - 1954)"
1024 \box \pad-markup #2 "THE UNANSWERED QUESTION"
1025 \box \pad-x #8 "A Cosmic Landscape"
1032 \box \pad-to-box #'(-5 . 20) #'(0 . 5)
1033 \bold "Largo to Presto"
1036 "String quartet keeps very even time,
1037 Flute quartet keeps very uneven time."
1041 @cindex graphic notation
1042 @cindex symbols, non-musical
1043 @cindex non-musical symbols
1044 @cindex notation, graphic
1048 @funindex \draw-circle
1049 @funindex draw-circle
1050 @funindex \filled-box
1051 @funindex filled-box
1054 @funindex \draw-line
1056 @funindex \arrow-head
1057 @funindex arrow-head
1059 Other graphic elements or symbols may be printed without requiring any
1060 text. As with any markup expression, such objects can be combined.
1062 @lilypond[quote,verbatim]
1065 \draw-circle #4 #0.4 ##f
1066 \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
1072 \draw-line #'(0 . 4)
1073 \arrow-head #Y #DOWN ##f
1078 @cindex embedded graphics
1079 @cindex images, embedding
1080 @cindex graphics, embedding
1085 @funindex \postscript
1086 @funindex postscript
1088 Advanced graphic features include the ability to include external
1089 image files converted to the Encapsulated PostScript format
1090 (@emph{eps}), or to directly embed graphics into the input file, using
1091 native PostScript code. In such a case, it may be useful to
1092 explicitly specify the size of the drawing, as demonstrated below:
1094 @lilypond[quote,verbatim,relative=1]
1097 \epsfile #X #10 #"./context-example.eps"
1098 \with-dimensions #'(0 . 6) #'(0 . 10)
1114 An exhaustive list of graphics-specific commands can be found in
1121 @ref{Editorial annotations}.
1126 Internals Reference:
1127 @rinternals{TextScript}.
1130 @file{scm/define-markup-commands.scm},
1131 @file{scm/stencil.scm}.
1134 @node Music notation inside markup
1135 @unnumberedsubsubsec Music notation inside markup
1137 @cindex notation inside markup
1138 @cindex music inside markup
1139 @cindex markup, music notation inside
1141 Various musical notation elements may be added to a score, inside a
1144 Notes and accidentals can be entered using markup commands:
1146 @lilypond[quote,verbatim,relative=2]
1150 \note-by-number #1 #1 #1.5
1153 \natural \semiflat \flat
1154 \sesquiflat \doubleflat
1158 \natural \semisharp \sharp
1159 \sesquisharp \doublesharp
1164 Other notation objects may also be printed
1167 @lilypond[quote,verbatim,relative=1]
1174 fis_\markup { \dynamic rf }
1185 More generally, any available musical symbol may be included
1186 separately in a markup object, as demonstrated below; an exhaustive
1187 list of these symbols and their names can be found in
1188 @ref{The Feta font}.
1190 @lilypond[quote,verbatim,relative=2]
1192 c'^\markup { \musicglyph #"eight" }
1194 c,8._\markup { \musicglyph #"clefs.G_change" }
1196 c2^\markup { \musicglyph #"timesig.neomensural94" }
1199 Another way of printing non-text glyphs is described in
1200 @ref{Fonts explained}. This is useful for printing braces of various
1203 The markup mode also supports diagrams for specific
1206 @lilypond[quote,verbatim,relative=2]
1208 \fret-diagram-terse #"x;x;o;2;3;2;"
1211 \harp-pedal #"^-v|--ov^"
1216 \musicglyph #"accordion.discant"
1218 \raise #0.5 \musicglyph #"accordion.dot"
1219 \raise #1.5 \musicglyph #"accordion.dot"
1223 @c The accordion diagram is actually taken from a snippet.
1226 Such diagrams are documented in @ref{Instrument Specific Markup}.
1228 @cindex score inside markup
1229 @cindex markup, score inside
1231 A whole score can even be nested inside a markup object. In such a
1232 case, the nested @code{\score} block must contain a @code{\layout}
1233 block, as demonstrated here:
1235 @lilypond[quote,verbatim,relative=1]
1238 \relative c' { c4 d e f }
1246 An exhaustive list of music notation related commands can be found in
1253 @ref{The Feta font},
1254 @ref{Fonts explained}.
1259 Internals Reference:
1260 @rinternals{TextScript}.
1263 @file{scm/define-markup-commands.scm},
1264 @file{scm/fret-diagrams.scm},
1265 @file{scm/harp-pedals.scm}.
1268 @node Multi-page markup
1269 @unnumberedsubsubsec Multi-page markup
1271 @cindex multi-page markup
1272 @cindex markup, multi-page
1273 @cindex markup text, multi-page
1274 @cindex text spread over multiple pages
1276 @funindex \markuplines
1277 @funindex markuplines
1278 @funindex \justified-lines
1279 @funindex justified-lines
1280 @funindex \wordwrap-lines
1281 @funindex wordwrap-lines
1283 Although standard markup objects are not breakable, a specific syntax
1284 makes it possible to enter lines of text that can spread over multiple
1287 @lilypond[quote,verbatim]
1290 A very long text of justified lines.
1294 Another very long paragraph.
1301 This syntax accepts a list of markups, that can be
1304 the result of a markup list command,
1308 a list of markup lists.
1311 An exhaustive list of markup list commands can be found in
1312 @ref{Text markup list commands}.
1317 @ref{Text markup list commands},
1323 @rextend{New markup list command definition}.
1325 Internals Reference:
1326 @rinternals{TextScript}.
1329 @file{scm/define-markup-commands.scm}.
1332 @funindex \markuplines
1333 @funindex markuplines
1336 @code{\markuplines}.
1343 This section presents the way fonts are handled, and how they may be
1348 * Single entry fonts::
1349 * Entire document fonts::
1352 @node Fonts explained
1353 @unnumberedsubsubsec Fonts explained
1356 @cindex fonts, explained
1357 @cindex braces, various sizes
1358 @cindex fonts, non-text in markup
1359 @cindex non-text fonts in markup
1361 @funindex font-interface
1363 Fonts are handled through several libraries. FontConfig is used to
1364 detect available fonts on the system; the selected fonts are rendered
1367 Music notation fonts can be described as a set of specific glyphs,
1368 ordered in several families. The following syntax allows various
1369 LilyPond @code{feta} non-text fonts to be used directly in markup
1372 @lilypond[quote,verbatim,relative=2]
1375 \override #'(font-encoding . fetaBraces)
1377 \override #'(font-encoding . fetaText)
1379 \override #'(font-encoding . fetaMusic)
1380 \lookup #"noteheads.s0petrucci"
1386 However, all these glyphs except the braces of various sizes contained
1387 in @code{fetaBraces} are available using the simpler syntax described
1388 in @ref{Music notation inside markup}.
1390 When using the glyphs contained in @code{fetaBraces}, the size of the
1391 brace is specified by the numerical part of the glyph name, in
1392 arbitrary units. Any integer from @code{0} to @code{575} inclusive
1393 may be specified, @code{0} giving the smallest brace. The optimum
1394 value must be determined by trial and error. These glyphs are all
1395 left braces; right braces may be obtained by rotation, see
1396 @ref{Rotating objects}.
1398 Three families of text fonts are made available: the @emph{roman}
1399 (serif) font, that defaults to New Century Schoolbook, the @emph{sans}
1400 font and the monospaced @emph{typewriter} font -- these last two
1401 families are determined by the Pango installation.
1403 Each family may include different shapes and series. The following
1404 example demonstrates the ability to select alternate families, shapes,
1405 series and sizes. The value supplied to @code{font-size} is the
1406 required change from the default size.
1408 @lilypond[quote,verbatim,relative=2]
1409 \override Score.RehearsalMark #'font-family = #'typewriter
1410 \mark \markup "Ouverture"
1411 \override Voice.TextScript #'font-shape = #'italic
1412 \override Voice.TextScript #'font-series = #'bold
1413 d2.^\markup "Allegro"
1414 \override Voice.TextScript #'font-size = #-3
1419 A similar syntax may be used in markup mode; however in this case it
1420 is preferable to use the simpler syntax explained in
1421 @ref{Selecting font and font size}:
1423 @lilypond[quote,verbatim]
1427 \override #'(font-shape . italic)
1428 \override #'(font-size . 4)
1432 \override #'(font-family . typewriter)
1434 \override #'(font-series . bold)
1438 \override #'(font-family . sans)
1445 Although it is easy to switch between preconfigured fonts, it is also
1446 possible to use other fonts, as explained in the following sections:
1447 @ref{Single entry fonts} and @ref{Entire document fonts}.
1452 @ref{The Feta font},
1453 @ref{Music notation inside markup},
1454 @ref{Selecting font and font size},
1458 @node Single entry fonts
1459 @unnumberedsubsubsec Single entry fonts
1461 Any font that is installed on the operating system and recognized by
1462 FontConfig may be used in a score, using the following syntax:
1464 @lilypond[quote,verbatim,relative=2]
1465 \override Staff.TimeSignature #'font-name = #"Bitstream Charter"
1466 \override Staff.TimeSignature #'font-size = #2
1470 \override #'(font-name . "Vera Bold")
1475 @cindex fonts, finding available
1476 @cindex finding available fonts
1477 @cindex listing available fonts
1478 @cindex available fonts, listing
1480 @funindex show-available-fonts
1482 The following command displays a list of all available fonts on the
1486 lilypond -dshow-available-fonts x
1492 @ref{Fonts explained},
1493 @ref{Entire document fonts}.
1498 @c A source file gets never installed...
1500 @c @file{lily/font-config-scheme.cc}.
1503 @node Entire document fonts
1504 @unnumberedsubsubsec Entire document fonts
1506 It is possible to change the fonts to be used as the default fonts in
1507 the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
1508 specifying them, in that order, as shown in the example below. For an
1509 explanation of fonts, see @ref{Fonts explained}.
1511 @cindex font families, setting
1512 @cindex fonts, changing for entire document
1514 @funindex make-pango-font-tree
1516 @lilypond[verbatim,quote]
1520 (make-pango-font-tree "Times New Roman"
1523 (/ myStaffSize 20)))
1530 \typewriter typewriter. }
1534 @c we don't do Helvetica / Courier, since GS incorrectly loads
1540 @ref{Fonts explained},
1541 @ref{Single entry fonts},
1542 @ref{Selecting font and font size},