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}.
104 @rlearning{Placement of objects}.
107 @ref{Formatting text},
108 @ref{Direction and placement},
109 @ref{Articulations and ornamentations}.
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
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,relative=2]
146 \override TextSpanner #'(bound-details left text) = "rit."
151 @cindex text spanners, formatting
152 @cindex formatting text spanners
155 The string to be printed is set through object properties. By default
156 it is printed in italic characters, but different formatting can be
157 obtained using @code{\markup} blocks, as described in
158 @ref{Formatting text}.
160 @lilypond[quote,relative=2,verbatim]
161 \override TextSpanner #'(bound-details left text) =
162 \markup { \upright "rit." }
167 The line style, as well as the text string, can be defined as an
168 object property. This syntax is described in @ref{Line styles}.
170 @funindex \textSpannerUp
171 @funindex textSpannerUp
172 @funindex \textSpannerDown
173 @funindex textSpannerDown
174 @funindex \textSpannerNeutral
175 @funindex textSpannerNeutral
179 @code{\textSpannerUp},
180 @code{\textSpannerDown},
181 @code{\textSpannerNeutral}.
185 LilyPond is only able to handle one text spanner per voice.
189 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
190 {dynamics-text-spanner-postfix.ly}
192 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
193 {dynamics-custom-text-spanner-postfix.ly}
199 @ref{Formatting text}.
203 @rlsr{Expressive marks}.
206 @rinternals{TextSpanner}.
210 @unnumberedsubsubsec Text marks
215 @cindex text on bar line
216 @cindex coda on bar line
217 @cindex segno on bar line
218 @cindex fermata on bar line
219 @cindex bar lines, symbols on
226 Various text elements may be added to a score using the syntax described
227 in @ref{Rehearsal marks}:
229 @c \mark needs to be placed on a separate line (it's not
230 @c attached to an object like \markup is). -vv
232 @lilypond[verbatim,quote,relative=2]
238 This syntax makes it possible to put any text on a bar line;
239 more complex text formatting may be added using a @code{\markup}
240 block, as described in @ref{Formatting text}:
242 @lilypond[quote,verbatim,relative=1]
244 \mark \markup { \italic { colla parte } }
250 This syntax also allows to print special signs, like coda, segno
251 or fermata, by specifying the appropriate symbol name as explained in
252 @ref{Music notation inside markup}:
254 @lilypond[quote,verbatim,relative=2]
256 \mark \markup { \musicglyph #"scripts.ufermata" }
261 Such objects are only typeset above the top staff of the score;
262 depending on whether they are specified at the end or the middle of a
263 bar, they can be placed above the bar line or between notes. When
264 specified at a line break, the mark will be printed at the beginning of
267 @lilypond[quote,verbatim,relative=2]
277 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
278 {printing-marks-at-the-end-of-a-line.ly}
280 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
281 {aligning-marks-with-various-notation-objects.ly}
283 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
284 {printing-marks-on-every-staff.ly}
289 @ref{Rehearsal marks},
290 @ref{Formatting text},
291 @ref{Music notation inside markup},
298 @rinternals{MarkEvent},
299 @rinternals{Mark_engraver},
300 @rinternals{RehearsalMark}.
304 @unnumberedsubsubsec Separate text
306 @cindex separate text
307 @cindex text, separate
308 @cindex standalone text
309 @cindex top-level text
310 @cindex text, top-level
311 @cindex text, standalone
316 A @code{\markup} block can exist by itself, outside of any
317 @code{\score} block, as a @qq{top-level expression}. This syntax
318 is described in @ref{File structure}.
320 @lilypond[verbatim,quote]
322 Tomorrow, and tomorrow, and tomorrow...
327 This allows printing text separately from the music, which is
328 particularly useful when the input file contains several music pieces,
329 as described in @ref{Multiple scores in a book}.
331 @lilypond[quote,verbatim]
336 Tomorrow, and tomorrow, and tomorrow...
343 Separate text blocks can be spread over multiple pages,
344 making it possible to print text documents or books entirely
345 within LilyPond. This feature, and the specific syntax it
346 requires, are described in @ref{Multi-page markup}.
351 @funindex \markuplines
352 @funindex markuplines
362 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
363 {stand-alone-two-column-markup.ly}
368 @ref{Formatting text},
369 @ref{File structure},
370 @ref{Multiple scores in a book},
371 @ref{Multi-page markup}.
377 @rinternals{TextScript}.
380 @node Formatting text
381 @subsection Formatting text
383 This section presents basic and advanced text formatting,
384 using the @code{\markup} mode specific syntax.
387 * Text markup introduction::
388 * Selecting font and font size::
390 * Graphic notation inside markup::
391 * Music notation inside markup::
392 * Multi-page markup::
395 @node Text markup introduction
396 @unnumberedsubsubsec Text markup introduction
406 A @code{\markup} block is used to typeset text with an extensible
407 syntax called @qq{markup mode}.
409 @cindex markup expressions
410 @cindex expressions, markup
411 @cindex markup syntax
412 @cindex syntax, markup
414 The markup syntax is similar to LilyPond's usual syntax: a
415 @code{\markup} expression is enclosed in curly braces
416 @code{@{@dots{} @}}. A single word is regarded as a minimal expression,
417 and therefore does not need to be enclosed with braces.
419 Unlike simple @qq{quoted text} indications, @code{\markup} blocks may
420 contain nested expressions or markup commands, entered using the
421 backslash @code{\} character. Such commands only affect the first
422 following expression.
424 @lilypond[quote,verbatim,relative=2]
426 a2^\markup { poco \italic più forte }
428 d2_\markup { \italic "string. assai" }
430 b1^\markup { \bold { molto \italic agitato } }
434 @cindex special characters in markup mode
435 @cindex markup mode, special characters
436 @cindex reserved characters, printing
437 @cindex printing reserved characters
438 @cindex printing special characters
439 @cindex quoted text in markup mode
440 @cindex markup mode, quoted text
442 A @code{\markup} block may also contain quoted text strings. Such
443 strings are treated as minimal text expressions, and therefore any
444 markup command or special character (such as @code{\} and @code{#})
445 will be printed verbatim without affecting the formatting of the text.
446 Double quotation marks themselves may be printed by preceding them
449 @lilypond[quote,verbatim,relative=2]
450 a1^"\italic markup..."
451 a_\markup { \italic "... prints \"italic\" letters!" }
455 To be treated as a distinct expression, a list of words needs to be
456 enclosed with double quotes or preceded by a command. The way markup
457 expressions are defined affects how these expressions will be stacked,
458 centered and aligned; in the following example, the second
459 @code{\markup} expression is treated the same as the first one:
461 @lilypond[quote,verbatim,relative=2]
462 c1^\markup { \center-column { a bbb c } }
463 c1^\markup { \center-column { a { bbb c } } }
464 c1^\markup { \center-column { a \line { bbb c } } }
465 c1^\markup { \center-column { a "bbb c" } }
468 Markups can be stored in variables. Such variables may be
469 directly attached to notes:
471 @lilypond[quote,verbatim]
472 allegro = \markup { \bold \large Allegro }
482 An exhaustive list of @code{\markup}-specific commands can be found in
483 @ref{Text markup commands}.
488 @ref{Text markup commands}.
494 @file{scm/markup.scm}.
498 Syntax errors for markup mode can be confusing.
501 @node Selecting font and font size
502 @unnumberedsubsubsec Selecting font and font size
504 @cindex font switching
505 @cindex changing fonts
506 @cindex switching fonts
515 Basic font switching is supported in markup mode:
517 @lilypond[quote,verbatim,relative=2]
520 \italic { non troppo \underline Vivo }
523 d,_\markup { \italic quasi \smallCaps Tromba }
539 The size of the characters can also be altered in different ways:
542 the font size can be set to predefined standard sizes,
545 the font size can be set to an absolute value,
548 the font size can also be changed relatively to its previous value.
552 The following example demonstrates these three methods:
554 @lilypond[quote,verbatim,relative=1]
561 \fontsize #5 Sinfonia
568 \magnify #0.6 { e sentimento } )
581 Text may be printed as subscript or superscript. By default these are
582 printed in a smaller size, but a normal size can be used as well:
584 @lilypond[quote,verbatim]
587 \line { 1 \super st movement }
588 \line { 1 \normal-size-super st movement
589 \sub { (part two) } }
594 @cindex font families
596 The markup mode provides an easy way to select alternate font
597 families. The default serif font, of roman type, is automatically
598 selected unless specified otherwise; on the last line of the following
599 example, there is no difference between the first and the second word.
601 @lilypond[quote,verbatim]
604 \line { Act \number 1 }
605 \line { \sans { Scene I. } }
606 \line { \typewriter { Verona. An open place. } }
607 \line { Enter \roman Valentine and Proteus. }
613 Some of these font families, used for specific items such as numbers
614 or dynamics, do not provide all characters, as mentioned in
615 @ref{New dynamic marks} and @ref{Manual repeat marks}.
617 @c \concat is actually documented in Align (it is not
618 @c a font-switching command). But we need it here. -vv
620 When used inside a word, some font-switching or formatting commands
621 may produce an unwanted blank space. This can easily be solved by
622 concatenating the text elements together:
624 @lilypond[quote,verbatim]
628 \concat { 1 \super st }
632 \concat { \dynamic p , }
633 \italic { con dolce espressione }
639 An exhaustive list of font switching commands and custom font usage
640 commands can be found in @ref{Font}.
642 Defining custom font sets is also possible, as explained in
651 @funindex \normalsize
678 @ref{New dynamic marks},
679 @ref{Manual repeat marks},
686 @rinternals{TextScript}.
689 @file{scm/define-markup-commands.scm}.
692 Using the font sizing commands @code{\teeny}, @code{\tiny},
693 @code{\small}, @code{\normalsize}, @code{\large}, and
694 @code{\huge} will lead to inconsistent line spacing compared to
695 using @code{\fontsize}.
699 @unnumberedsubsubsec Text alignment
701 @cindex text, aligning
702 @cindex aligning text
703 @cindex aligning markup text
704 @cindex aligning markups
705 @cindex markups, aligning
706 @cindex markup text, aligning
708 This subsection discusses how to place text in markup mode. Markup
709 objects can also be moved as a whole, using the syntax described in
710 @rlearning{Moving objects}.
712 @c Padding commands should be mentioned on this page, but
713 @c most of these require \box to be more clearly illustrated. -vv
715 @cindex text, horizontal alignment
716 @cindex horizontal text alignment
718 @funindex \left-align
720 @funindex \center-align
721 @funindex center-align
722 @funindex \right-align
723 @funindex right-align
725 Markup objects may be aligned in different ways. By default, a text
726 indication is aligned on its left edge: in the following example,
727 there is no difference between the first and the second markup.
729 @lilypond[quote,verbatim,relative=2]
732 d-\markup { \left-align poco }
734 d-\markup { \center-align { poco } }
736 d-\markup { \right-align poco }
742 Horizontal alignment may be fine-tuned using a numeric value:
744 @lilypond[quote,verbatim,relative=2]
745 a1-\markup { \halign #-1 poco }
747 a,-\markup { \halign #0 poco }
749 a,-\markup { \halign #0.5 poco }
751 a,-\markup { \halign #2 poco }
755 Some objects may have alignment procedures of their own, and therefore
756 are not affected by these commands. It is possible to move such
757 markup objects as a whole, as shown for instance in
760 @cindex text, vertical alignment
761 @cindex vertical text alignment
770 @c QUERY Should the function of ``\null'' be clarified? rp
772 Vertical alignment is a bit more complex. As stated above, markup
773 objects can be moved as a whole; however, it is also possible to move
774 specific elements inside a markup block. In this case, the element to
775 be moved needs to be preceded with an @emph{anchor point}, that can be
776 another markup element or an invisible object. The following example
777 demonstrates these two possibilities; the last markup in this example
778 has no anchor point, and therefore is not moved.
780 @lilypond[quote,verbatim,relative=1]
783 \raise #2 { Scène 1 }
788 \lower #4 \bold { Très modéré }
792 \raise #4 \italic { Une forêt. }
797 @funindex \general-align
798 @funindex general-align
801 @funindex \translate-scaled
802 @funindex translate-scaled
804 Some commands can affect both the horizontal and vertical alignment of
805 text objects in markup mode. Any object affected by these commands
806 must be preceded with an anchor point:
808 @lilypond[quote,verbatim,relative=1]
811 \translate #'(-1 . 2) "Scène 1"
816 \general-align #Y #3.2 \bold "Très modéré"
821 \translate-scaled #'(-1 . 2) \teeny "Une forêt."
826 @cindex multi-line markup
827 @cindex markup, multi-line
828 @cindex multi-line text
829 @cindex text, multi-line
830 @cindex text in columns
831 @cindex columns, text
835 @funindex \center-column
836 @funindex center-column
838 A markup object may include several lines of text. In the following
839 example, each element or expression is placed on its own line, either
840 left-aligned or centered:
842 @lilypond[quote,verbatim]
858 @cindex centering text on the page
859 @cindex text, centering on the page
860 @cindex markup, centering on the page
865 Similarly, a list of elements or expressions may be spread to fill the
866 entire horizontal line width (if there is only one element, it will be
867 centered on the page). These expressions can, in turn, include
868 multi-line text or any other markup expression:
870 @lilypond[quote,verbatim]
873 \line { William S. Gilbert }
875 \huge \smallCaps "The Mikado"
877 \smallCaps "The Town of Titipu"
879 \line { Sir Arthur Sullivan }
887 @cindex wordwrapped text
888 @cindex justified text
889 @cindex text, justified
890 @cindex text, wordwrapped
891 @cindex markup text, wordwrapped
892 @cindex markup text, justified
899 Long text indications can also be automatically wrapped accordingly to
900 the given line width. These will be either left-aligned or justified,
901 as shown in the following example.
903 @lilypond[quote,verbatim]
906 \line \smallCaps { La vida breve }
907 \line \bold { Acto I }
909 (La escena representa el corral de una casa de
910 gitanos en el AlbaicÃn de Granada. Al fondo una
911 puerta por la que se ve el negro interior de
912 una Fragua, iluminado por los rojos resplandores
917 \line \bold { Acto II }
918 \override #'(line-width . 50)
920 (Calle de Granada. Fachada de la casa de Carmela
921 y su hermano Manuel con grandes ventanas abiertas
922 a través de las que se ve el patio
923 donde se celebra una alegre fiesta)
929 @cindex text alignment commands
930 @cindex markup text alignment commands
931 @cindex alignment, text, commands
933 An exhaustive list of text alignment commands can be found in
939 @rlearning{Moving objects}.
949 @rinternals{TextScript}.
952 @file{scm/define-markup-commands.scm}.
955 @node Graphic notation inside markup
956 @unnumberedsubsubsec Graphic notation inside markup
958 @cindex graphics, embedding
959 @cindex drawing graphic objects
960 @cindex graphic objects, drawing
961 @cindex embedding graphic objects
962 @cindex graphic objects, embedding
964 Various graphic objects may be added to a score, using markup
967 @cindex decorating text
969 @cindex text, framing
970 @cindex text, decorating
971 @cindex markup text, decorating
972 @cindex markup text, framing
978 @funindex \rounded-box
979 @funindex rounded-box
985 Some markup commands allow decoration of text elements with graphics,
986 as demonstrated in the following example.
988 @lilypond[quote,verbatim]
997 \bracket "1866 - 1925"
1000 \rounded-box \bold Prelude
1005 @cindex padding around text
1006 @cindex text padding
1007 @cindex markup text padding
1009 @funindex \pad-markup
1010 @funindex pad-markup
1013 @funindex \pad-to-box
1014 @funindex pad-to-box
1015 @funindex \pad-around
1016 @funindex pad-around
1018 Some commands may require an increase in the padding around the text;
1019 this is achieved with some markup commands exhaustively described in
1022 @lilypond[quote,verbatim]
1023 \markup \fill-line {
1025 \box "Charles Ives (1874 - 1954)"
1027 \box \pad-markup #2 "THE UNANSWERED QUESTION"
1028 \box \pad-x #8 "A Cosmic Landscape"
1035 \box \pad-to-box #'(-5 . 20) #'(0 . 5)
1036 \bold "Largo to Presto"
1039 "String quartet keeps very even time,
1040 Flute quartet keeps very uneven time."
1044 @cindex graphic notation
1045 @cindex symbols, non-musical
1046 @cindex non-musical symbols
1047 @cindex notation, graphic
1051 @funindex \draw-circle
1052 @funindex draw-circle
1053 @funindex \filled-box
1054 @funindex filled-box
1057 @funindex \draw-line
1059 @funindex \arrow-head
1060 @funindex arrow-head
1062 Other graphic elements or symbols may be printed without requiring any
1063 text. As with any markup expression, such objects can be combined.
1065 @lilypond[quote,verbatim]
1068 \draw-circle #4 #0.4 ##f
1069 \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
1075 \draw-line #'(0 . 4)
1076 \arrow-head #Y #DOWN ##f
1081 @cindex embedded graphics
1082 @cindex images, embedding
1083 @cindex graphics, embedding
1088 @funindex \postscript
1089 @funindex postscript
1091 Advanced graphic features include the ability to include external
1092 image files converted to the Encapsulated PostScript format
1093 (@emph{eps}), or to directly embed graphics into the input file, using
1094 native PostScript code. In such a case, it may be useful to
1095 explicitly specify the size of the drawing, as demonstrated below:
1097 @lilypond[quote,verbatim,relative=1]
1100 \epsfile #X #10 #"./context-example.eps"
1101 \with-dimensions #'(0 . 6) #'(0 . 10)
1117 An exhaustive list of graphics-specific commands can be found in
1124 @ref{Editorial annotations},
1130 Internals Reference:
1131 @rinternals{TextScript}.
1134 @file{scm/define-markup-commands.scm},
1135 @file{scm/stencil.scm}.
1138 @node Music notation inside markup
1139 @unnumberedsubsubsec Music notation inside markup
1141 @cindex notation inside markup
1142 @cindex music inside markup
1143 @cindex markup, music notation inside
1145 Various musical notation elements may be added to a score, inside a
1148 Notes and accidentals can be entered using markup commands:
1150 @lilypond[quote,verbatim,relative=2]
1154 \note-by-number #1 #1 #1.5
1157 \natural \semiflat \flat
1158 \sesquiflat \doubleflat
1162 \natural \semisharp \sharp
1163 \sesquisharp \doublesharp
1168 Other notation objects may also be printed
1171 @lilypond[quote,verbatim,relative=1]
1178 fis_\markup { \dynamic rf }
1189 More generally, any available musical symbol may be included
1190 separately in a markup object, as demonstrated below; an exhaustive
1191 list of these symbols and their names can be found in
1192 @ref{The Feta font}.
1194 @lilypond[quote,verbatim,relative=2]
1196 c'^\markup { \musicglyph #"eight" }
1198 c,8._\markup { \musicglyph #"clefs.G_change" }
1200 c2^\markup { \musicglyph #"timesig.neomensural94" }
1203 Another way of printing non-text glyphs is described in
1204 @ref{Fonts explained}. This is useful for printing braces of various
1207 The markup mode also supports diagrams for specific
1210 @lilypond[quote,verbatim,relative=2]
1212 \fret-diagram-terse #"x;x;o;2;3;2;"
1215 \harp-pedal #"^-v|--ov^"
1220 \musicglyph #"accordion.discant"
1222 \raise #0.5 \musicglyph #"accordion.dot"
1223 \raise #1.5 \musicglyph #"accordion.dot"
1227 @c The accordion diagram is actually taken from a snippet.
1230 Such diagrams are documented in @ref{Instrument Specific Markup}.
1232 @cindex score inside markup
1233 @cindex markup, score inside
1235 A whole score can even be nested inside a markup object. In such a
1236 case, the nested @code{\score} block must contain a @code{\layout}
1237 block, as demonstrated here:
1239 @lilypond[quote,verbatim,relative=1]
1242 \relative c' { c4 d e f }
1250 An exhaustive list of music notation related commands can be found in
1257 @ref{The Feta font},
1258 @ref{Fonts explained}.
1263 Internals Reference:
1264 @rinternals{TextScript}.
1267 @file{scm/define-markup-commands.scm},
1268 @file{scm/fret-diagrams.scm},
1269 @file{scm/harp-pedals.scm}.
1272 @node Multi-page markup
1273 @unnumberedsubsubsec Multi-page markup
1275 @cindex multi-page markup
1276 @cindex markup, multi-page
1277 @cindex markup text, multi-page
1278 @cindex text spread over multiple pages
1280 @funindex \markuplines
1281 @funindex markuplines
1282 @funindex \justified-lines
1283 @funindex justified-lines
1284 @funindex \wordwrap-lines
1285 @funindex wordwrap-lines
1287 Although standard markup objects are not breakable, a specific syntax
1288 makes it possible to enter lines of text that can spread over multiple
1291 @lilypond[quote,verbatim]
1294 A very long text of justified lines.
1298 Another very long paragraph.
1305 This syntax accepts a list of markups, that can be
1308 the result of a markup list command,
1312 a list of markup lists.
1315 An exhaustive list of markup list commands can be found in
1316 @ref{Text markup list commands}.
1321 @ref{Text markup list commands},
1327 @rextend{New markup list command definition}.
1329 Internals Reference:
1330 @rinternals{TextScript}.
1333 @file{scm/define-markup-commands.scm}.
1336 @funindex \markuplines
1337 @funindex markuplines
1340 @code{\markuplines}.
1347 This section presents the way fonts are handled, and how they may be
1352 * Single entry fonts::
1353 * Entire document fonts::
1356 @node Fonts explained
1357 @unnumberedsubsubsec Fonts explained
1360 @cindex fonts, explained
1361 @cindex braces, various sizes
1362 @cindex fonts, non-text in markup
1363 @cindex non-text fonts in markup
1365 @funindex font-interface
1367 Fonts are handled through several libraries. FontConfig is used to
1368 detect available fonts on the system; the selected fonts are rendered
1371 Music notation fonts can be described as a set of specific glyphs,
1372 ordered in several families. The following syntax allows various
1373 LilyPond @code{feta} non-text fonts to be used directly in markup
1376 @lilypond[quote,verbatim,relative=2]
1379 \override #'(font-encoding . fetaBraces)
1381 \override #'(font-encoding . fetaText)
1383 \override #'(font-encoding . fetaMusic)
1384 \lookup #"noteheads.s0petrucci"
1390 However, all these glyphs except the braces of various sizes contained
1391 in @code{fetaBraces} are available using the simpler syntax described
1392 in @ref{Music notation inside markup}.
1394 When using the glyphs contained in @code{fetaBraces}, the size of the
1395 brace is specified by the numerical part of the glyph name, in
1396 arbitrary units. Any integer from @code{0} to @code{575} inclusive
1397 may be specified, @code{0} giving the smallest brace. The optimum
1398 value must be determined by trial and error. These glyphs are all
1399 left braces; right braces may be obtained by rotation, see
1400 @ref{Rotating objects}.
1402 Three families of text fonts are made available: the @emph{roman}
1403 (serif) font, that defaults to New Century Schoolbook, the
1404 @emph{sans} font and the monospaced @emph{typewriter} font -- these
1405 last two families are determined by the Pango installation.
1407 Each family may include different shapes and series. The following
1408 example demonstrates the ability to select alternate families, shapes,
1409 series and sizes. The value supplied to @code{font-size} is the
1410 required change from the default size.
1412 @lilypond[quote,verbatim,relative=2]
1413 \override Score.RehearsalMark #'font-family = #'typewriter
1414 \mark \markup "Ouverture"
1415 \override Voice.TextScript #'font-shape = #'italic
1416 \override Voice.TextScript #'font-series = #'bold
1417 d2.^\markup "Allegro"
1418 \override Voice.TextScript #'font-size = #-3
1423 A similar syntax may be used in markup mode; however in this case it
1424 is preferable to use the simpler syntax explained in
1425 @ref{Selecting font and font size}:
1427 @lilypond[quote,verbatim]
1431 \override #'(font-shape . italic)
1432 \override #'(font-size . 4)
1436 \override #'(font-family . typewriter)
1438 \override #'(font-series . bold)
1442 \override #'(font-family . sans)
1449 Although it is easy to switch between preconfigured fonts, it is also
1450 possible to use other fonts, as explained in the following sections:
1451 @ref{Single entry fonts} and @ref{Entire document fonts}.
1456 @ref{The Feta font},
1457 @ref{Music notation inside markup},
1458 @ref{Rotating objects},
1459 @ref{Selecting font and font size},
1463 @node Single entry fonts
1464 @unnumberedsubsubsec Single entry fonts
1466 Any font that is installed on the operating system and recognized by
1467 FontConfig may be used in a score, using the following syntax:
1469 @lilypond[quote,verbatim,relative=2]
1470 \override Staff.TimeSignature #'font-name = #"Bitstream Charter"
1471 \override Staff.TimeSignature #'font-size = #2
1475 \override #'(font-name . "Vera Bold")
1480 @cindex fonts, finding available
1481 @cindex finding available fonts
1482 @cindex listing available fonts
1483 @cindex available fonts, listing
1485 @funindex show-available-fonts
1487 The following command displays a list of all available fonts on the
1491 lilypond -dshow-available-fonts x
1497 @ref{Fonts explained},
1498 @ref{Entire document fonts}.
1503 @c A source file gets never installed...
1505 @c @file{lily/font-config-scheme.cc}.
1508 @node Entire document fonts
1509 @unnumberedsubsubsec Entire document fonts
1511 It is possible to change the fonts to be used as the default fonts in
1512 the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
1513 specifying them, in that order, as shown in the example below. For an
1514 explanation of fonts, see @ref{Fonts explained}.
1516 @cindex font families, setting
1517 @cindex fonts, changing for entire document
1519 @funindex make-pango-font-tree
1521 @lilypond[verbatim,quote]
1525 (make-pango-font-tree "Times New Roman"
1528 (/ myStaffSize 20)))
1535 \typewriter typewriter. }
1539 @c we don't do Helvetica / Courier, since GS incorrectly loads
1545 @ref{Fonts explained},
1546 @ref{Single entry fonts},
1547 @ref{Selecting font and font size},