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 \textLengthOff
99 @code{\textLengthOff}.
104 @rlearning{Placement of objects}.
107 @ref{Formatting text},
108 @ref{Direction and placement},
109 @ref{Articulations and ornamentations}.
115 @rinternals{TextScript}.
117 @cindex text outside margin
118 @cindex margin, text running over
119 @cindex text, keeping inside margin
120 @cindex lyrics, keeping inside margin
123 Checking to make sure that text scripts and lyrics are within the
124 margins requires additional calculations. In cases where slightly faster
125 performance is desired, use
128 \override Score.PaperColumn.keep-inside-line = ##f
133 @unnumberedsubsubsec Text spanners
135 @cindex text spanners
137 Some performance indications, e.g., @notation{rallentando} or
138 @notation{accelerando}, are written as text and are extended over
139 multiple notes with dotted lines. Such objects, called
140 @qq{spanners}, may be created from one note to another using the
143 @lilypond[verbatim,quote]
145 \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,verbatim]
162 \override TextSpanner.bound-details.left.text =
163 \markup { \upright "rit." }
169 The line style, as well as the text string, can be defined as an
170 object property. This syntax is described in @ref{Line styles}.
172 @funindex \textSpannerUp
173 @funindex \textSpannerDown
174 @funindex \textSpannerNeutral
178 @code{\textSpannerUp},
179 @code{\textSpannerDown},
180 @code{\textSpannerNeutral}.
184 LilyPond is only able to handle one text spanner per voice.
188 @lilypondfile[verbatim,quote,texidoc,doctitle]
189 {dynamics-text-spanner-postfix.ly}
191 @lilypondfile[verbatim,quote,texidoc,doctitle]
192 {dynamics-custom-text-spanner-postfix.ly}
198 @ref{Formatting text}.
202 @rlsr{Expressive marks}.
205 @rinternals{TextSpanner}.
209 @unnumberedsubsubsec Text marks
214 @cindex text on bar line
215 @cindex coda on bar line
216 @cindex segno on bar line
217 @cindex fermata on bar line
218 @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]
240 This syntax makes it possible to put any text on a bar line;
241 more complex text formatting may be added using a @code{\markup}
242 block, as described in @ref{Formatting text}:
244 @lilypond[quote,verbatim]
247 \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]
261 \mark \markup { \musicglyph #"scripts.ufermata" }
267 Such objects are only typeset above the top staff of the score;
268 depending on whether they are specified at the end or the middle of a
269 bar, they can be placed above the bar line or between notes. When
270 specified at a line break, the mark will be printed at the beginning of
273 @lilypond[quote,verbatim,ragged-right]
282 @funindex \markLengthOn
283 @funindex \markLengthOff
286 @code{\markLengthOn},
287 @code{\markLengthOff}.
292 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
293 {printing-marks-at-the-end-of-a-line.ly}
295 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
296 {printing-marks-on-every-staff.ly}
300 @ref{Rehearsal marks},
301 @ref{Formatting text},
302 @ref{Music notation inside markup},
303 @ref{The Emmentaler font}.
309 @rinternals{MarkEvent},
310 @rinternals{Mark_engraver},
311 @rinternals{RehearsalMark}.
315 @unnumberedsubsubsec Separate text
317 @cindex separate text
318 @cindex text, separate
319 @cindex standalone text
320 @cindex top-level text
321 @cindex text, top-level
322 @cindex text, standalone
326 A @code{\markup} block can exist by itself, outside of any
327 @code{\score} block, as a @qq{top-level expression}. This syntax
328 is described in @ref{File structure}.
330 @lilypond[verbatim,quote]
332 Tomorrow, and tomorrow, and tomorrow...
337 This allows printing text separately from the music, which is
338 particularly useful when the input file contains several music pieces,
339 as described in @ref{Multiple scores in a book}.
341 @lilypond[quote,verbatim]
346 Tomorrow, and tomorrow, and tomorrow...
353 Separate text blocks can be spread over multiple pages,
354 making it possible to print text documents or books entirely
355 within LilyPond. This feature, and the specific syntax it
356 requires, are described in @ref{Multi-page markup}.
360 @funindex \markuplist
370 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
371 {stand-alone-two-column-markup.ly}
375 @ref{Formatting text},
376 @ref{File structure},
377 @ref{Multiple scores in a book},
378 @ref{Multi-page markup}.
384 @rinternals{TextScript}.
387 @node Formatting text
388 @subsection Formatting text
390 This section presents basic and advanced text formatting,
391 using the @code{\markup} mode specific syntax.
394 * Text markup introduction::
395 * Selecting font and font size::
397 * Graphic notation inside markup::
398 * Music notation inside markup::
399 * Multi-page markup::
402 @node Text markup introduction
403 @unnumberedsubsubsec Text markup introduction
412 A @code{\markup} block is used to typeset text with an extensible
413 syntax called @qq{markup mode}.
415 @cindex markup expressions
416 @cindex expressions, markup
417 @cindex markup syntax
418 @cindex syntax, markup
420 The markup syntax is similar to LilyPond's usual syntax: a
421 @code{\markup} expression is enclosed in curly braces
422 @code{@{@dots{} @}}. A single word is regarded as a minimal expression,
423 and therefore does not need to be enclosed with braces.
425 Unlike simple @qq{quoted text} indications, @code{\markup} blocks may
426 contain nested expressions or markup commands, entered using the
427 backslash @code{\} character. Such commands only affect the first
428 following expression.
430 @lilypond[quote,verbatim]
433 a2^\markup { poco \italic più forte }
435 d2_\markup { \italic "string. assai" }
437 b1^\markup { \bold { molto \italic agitato } }
442 @cindex special characters in markup mode
443 @cindex markup mode, special characters
444 @cindex reserved characters, printing
445 @cindex printing reserved characters
446 @cindex printing special characters
447 @cindex quoted text in markup mode
448 @cindex markup mode, quoted text
450 A @code{\markup} block may also contain quoted text strings. Such
451 strings are treated as minimal text expressions, and therefore any
452 markup command or special character (such as @code{\} and@tie{}@code{#})
453 will be printed verbatim without affecting the formatting of the text.
454 Double quotation marks themselves may be printed by preceding them
457 @lilypond[quote,verbatim]
459 a'1^"\italic markup..."
460 a_\markup { \italic "... prints \"italic\" letters!" }
465 To be treated as a distinct expression, a list of words needs to be
466 enclosed with double quotes or preceded by a command. The way markup
467 expressions are defined affects how these expressions will be stacked,
468 centered and aligned; in the following example, the second
469 @code{\markup} expression is treated the same as the first one:
471 @lilypond[quote,verbatim]
473 c1^\markup { \center-column { a bbb c } }
474 c1^\markup { \center-column { a { bbb c } } }
475 c1^\markup { \center-column { a \line { bbb c } } }
476 c1^\markup { \center-column { a "bbb c" } }
480 Markups can be stored in variables. Such variables may be
481 directly attached to notes:
483 @lilypond[quote,verbatim]
484 allegro = \markup { \bold \large Allegro }
494 An exhaustive list of @code{\markup}-specific commands can be found in
495 @ref{Text markup commands}.
499 @ref{Text markup commands}.
505 @file{scm/markup.scm}.
508 Syntax error messages for markup mode can be confusing.
511 @node Selecting font and font size
512 @unnumberedsubsubsec Selecting font and font size
514 @cindex font switching
515 @cindex changing fonts
516 @cindex switching fonts
522 Basic font switching is supported in markup mode:
524 @lilypond[quote,verbatim]
528 \italic { non troppo \underline Vivo }
531 d,_\markup { \italic quasi \smallCaps Tromba }
539 @funindex \abs-fontsize
545 The font size can be altered, relative to the global staff size, in a
546 number of different ways.
548 It can be set to predefined size.
550 @lilypond[quote,verbatim]
552 b1_\markup { \huge Sinfonia }
553 b1^\markup { \teeny da }
554 b1-\markup { \normalsize camera }
558 It can be set relative to its previous value.
560 @lilypond[quote,verbatim]
562 b1_\markup { \larger Sinfonia }
563 b1^\markup { \smaller da }
564 b1-\markup { \magnify #0.6 camera }
568 It can be increased or decreased relative to the value set by the
571 @lilypond[quote,verbatim]
573 b1_\markup { \fontsize #-2 Sinfonia }
574 b1^\markup { \fontsize #1 da }
575 b1-\markup { \fontsize #3 camera }
579 It can also be set to a fixed point-size, regardless of the global staff
582 @lilypond[quote,verbatim]
584 b1_\markup { \abs-fontsize #20 Sinfonia }
585 b1^\markup { \abs-fontsize #8 da }
586 b1-\markup { \abs-fontsize #14 camera }
590 If the text includes spaces, then it is best to put it all inside quote
591 marks, so that the size of each space is appropriate for the size of the
594 @lilypond[quote,verbatim]
595 \markup \fontsize #6 \bold { Sinfonia da camera }
596 \markup \fontsize #6 \bold { "Sinfonia da camera" }
604 @funindex \normal-size-super
606 Text may be printed as subscript or superscript. By default these are
607 printed in a smaller size, but a normal size can be used as well:
609 @lilypond[quote,verbatim]
612 \line { 1 \super st movement }
613 \line { 1 \normal-size-super st movement
614 \sub { (part two) } }
619 @cindex font families
621 The markup mode provides an easy way to select alternate font
622 families. The default serif font, of roman type, is automatically
623 selected unless specified otherwise; on the last line of the following
624 example, there is no difference between the first and the second word.
626 @lilypond[quote,verbatim]
629 \line { Act \number 1 }
630 \line { \sans { Scene I. } }
631 \line { \typewriter { Verona. An open place. } }
632 \line { Enter \roman Valentine and Proteus. }
638 Some of these font families, used for specific items such as numbers
639 or dynamics, do not provide all characters, as mentioned in
640 @ref{New dynamic marks} and @ref{Manual repeat marks}.
642 @c \concat is actually documented in Align (it is not
643 @c a font-switching command). But we need it here. -vv
645 When used inside a word, some font-switching or formatting commands
646 may produce an unwanted blank space. This can easily be solved by
647 concatenating the text elements together:
649 @lilypond[quote,verbatim]
653 \concat { 1 \super st }
657 \concat { \dynamic p , }
658 \italic { con dolce espressione }
664 An exhaustive list of font switching commands and custom font usage
665 commands can be found in @ref{Font}.
667 Defining custom font sets is also possible, as explained in
673 @funindex \normalsize
694 @ref{New dynamic marks},
695 @ref{Manual repeat marks},
699 @file{scm/define-markup-commands.scm}.
705 @rinternals{TextScript}.
708 Using the font sizing commands @code{\teeny}, @code{\tiny},
709 @code{\small}, @code{\normalsize}, @code{\large}, and
710 @code{\huge} will lead to inconsistent line spacing compared to
711 using @code{\fontsize}.
715 @unnumberedsubsubsec Text alignment
717 @cindex text, aligning
718 @cindex aligning text
719 @cindex aligning markup text
720 @cindex aligning markups
721 @cindex markups, aligning
722 @cindex markup text, aligning
724 This subsection discusses how to place text in markup mode. Markup
725 objects can also be moved as a whole, using the syntax described in
726 @rlearning{Moving objects}.
728 @c Padding commands should be mentioned on this page, but
729 @c most of these require \box to be more clearly illustrated. -vv
731 @cindex text, horizontal alignment
732 @cindex horizontal text alignment
734 @funindex \left-align
735 @funindex \center-align
736 @funindex \right-align
738 Markup objects may be aligned in different ways. By default, a text
739 indication is aligned on its left edge: in the following example,
740 there is no difference between the first and the second markup.
742 @lilypond[quote,verbatim]
744 d''1-\markup { poco }
746 d-\markup { \left-align poco }
748 d-\markup { \center-align { poco } }
750 d-\markup { \right-align poco }
756 Horizontal alignment may be fine-tuned using a numeric value:
758 @lilypond[quote,verbatim]
760 a'1-\markup { \halign #-1 poco }
762 a,-\markup { \halign #0 poco }
764 a,-\markup { \halign #0.5 poco }
766 a,-\markup { \halign #2 poco }
771 Some objects may have alignment procedures of their own, and therefore
772 are not affected by these commands. It is possible to move such
773 markup objects as a whole, as shown for instance in
776 @cindex text, vertical alignment
777 @cindex vertical text alignment
783 @c QUERY Should the function of ``\null'' be clarified? rp
785 Vertical alignment is a bit more complex. As stated above, markup
786 objects can be moved as a whole; however, it is also possible to move
787 specific elements inside a markup block. In this case, the element to
788 be moved needs to be preceded with an @emph{anchor point}, that can be
789 another markup element or an invisible object. The following example
790 demonstrates these two possibilities; the last markup in this example
791 has no anchor point, and therefore is not moved.
793 @lilypond[quote,verbatim]
797 \raise #2 { Scène 1 }
802 \lower #4 \bold { Très modéré }
806 \raise #4 \italic { Une forêt. }
812 @funindex \general-align
814 @funindex \translate-scaled
816 Some commands can affect both the horizontal and vertical alignment of
817 text objects in markup mode. Any object affected by these commands
818 must be preceded with an anchor point:
820 @lilypond[quote,verbatim]
824 \translate #'(-1 . 2) "Scène 1"
829 \general-align #Y #3.2 \bold "Très modéré"
834 \translate-scaled #'(-1 . 2) \teeny "Une forêt."
840 @cindex multi-line markup
841 @cindex markup, multi-line
842 @cindex multi-line text
843 @cindex text, multi-line
844 @cindex text in columns
845 @cindex columns, text
848 @funindex \center-column
850 A markup object may include several lines of text. In the following
851 example, each element or expression is placed on its own line, either
852 left-aligned or centered:
854 @lilypond[quote,verbatim]
870 @cindex centering text on the page
871 @cindex text, centering on the page
872 @cindex markup, centering on the page
876 Similarly, a list of elements or expressions may be spread to fill the
877 entire horizontal line width (if there is only one element, it will be
878 centered on the page). These expressions can, in turn, include
879 multi-line text or any other markup expression:
881 @lilypond[quote,verbatim]
884 \line { William S. Gilbert }
886 \huge \smallCaps "The Mikado"
888 \smallCaps "The Town of Titipu"
890 \line { Sir Arthur Sullivan }
898 @cindex wordwrapped text
899 @cindex justified text
900 @cindex text, justified
901 @cindex text, wordwrapped
902 @cindex markup text, wordwrapped
903 @cindex markup text, justified
908 Long text indications can also be automatically wrapped accordingly to
909 the given line width. These will be either left-aligned or justified,
910 as shown in the following example.
912 @lilypond[quote,verbatim]
915 \line \smallCaps { La vida breve }
916 \line \bold { Acto I }
918 (La escena representa el corral de una casa de
919 gitanos en el AlbaicÃn de Granada. Al fondo una
920 puerta por la que se ve el negro interior de
921 una Fragua, iluminado por los rojos resplandores
926 \line \bold { Acto II }
927 \override #'(line-width . 50)
929 (Calle de Granada. Fachada de la casa de Carmela
930 y su hermano Manuel con grandes ventanas abiertas
931 a través de las que se ve el patio
932 donde se celebra una alegre fiesta)
938 @cindex text alignment commands
939 @cindex markup text alignment commands
940 @cindex alignment, text, commands
942 An exhaustive list of text alignment commands can be found in
947 @rlearning{Moving objects}.
954 @file{scm/define-markup-commands.scm}.
960 @rinternals{TextScript}.
963 @node Graphic notation inside markup
964 @unnumberedsubsubsec Graphic notation inside markup
966 @cindex graphics, embedding
967 @cindex drawing graphic objects
968 @cindex graphic objects, drawing
969 @cindex embedding graphic objects
970 @cindex graphic objects, embedding
972 Various graphic objects may be added to a score, using markup
975 @cindex decorating text
977 @cindex text, framing
978 @cindex text, decorating
979 @cindex markup text, decorating
980 @cindex markup text, framing
984 @funindex \rounded-box
988 Some markup commands allow decoration of text elements with graphics,
989 as demonstrated in the following example.
991 @lilypond[quote,verbatim]
1000 \bracket "1866 - 1925"
1003 \rounded-box \bold Prelude
1008 @cindex padding around text
1009 @cindex text padding
1010 @cindex markup text padding
1012 @funindex \pad-markup
1014 @funindex \pad-to-box
1015 @funindex \pad-around
1017 Some commands may require an increase in the padding around the text;
1018 this is achieved with some markup commands exhaustively described in
1021 @lilypond[quote,verbatim]
1022 \markup \fill-line {
1024 \box "Charles Ives (1874 - 1954)"
1026 \box \pad-markup #2 "THE UNANSWERED QUESTION"
1027 \box \pad-x #8 "A Cosmic Landscape"
1034 \box \pad-to-box #'(-5 . 20) #'(0 . 5)
1035 \bold "Largo to Presto"
1038 "String quartet keeps very even time,
1039 Flute quartet keeps very uneven time."
1043 @cindex graphic notation
1044 @cindex symbols, non-musical
1045 @cindex non-musical symbols
1046 @cindex notation, graphic
1049 @funindex \draw-circle
1050 @funindex \filled-box
1052 @funindex \draw-line
1053 @funindex \arrow-head
1055 Other graphic elements or symbols may be printed without requiring any
1056 text. As with any markup expression, such objects can be combined.
1058 @lilypond[quote,verbatim]
1061 \draw-circle #4 #0.4 ##f
1062 \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
1068 \draw-line #'(0 . 4)
1069 \arrow-head #Y #DOWN ##f
1074 @cindex embedded graphics
1075 @cindex images, embedding
1076 @cindex graphics, embedding
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,fragment]
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
1115 @ref{Editorial annotations},
1119 @file{scm/define-markup-commands.scm},
1120 @file{scm/stencil.scm}.
1125 Internals Reference:
1126 @rinternals{TextScript}.
1129 @node Music notation inside markup
1130 @unnumberedsubsubsec Music notation inside markup
1132 @cindex notation inside markup
1133 @cindex music inside markup
1134 @cindex markup, music notation inside
1136 Various musical notation elements may be added to a score, inside a
1139 Notes and accidentals can be entered using markup commands:
1141 @lilypond[quote,verbatim,fragment]
1145 \note-by-number #1 #1 #1.5
1148 \natural \semiflat \flat
1149 \sesquiflat \doubleflat
1153 \natural \semisharp \sharp
1154 \sesquisharp \doublesharp
1159 Other notation objects may also be printed
1162 @lilypond[quote,verbatim]
1165 ees\finger \markup \tied-lyric #"4~1"
1166 fis_\markup { \dynamic rf }
1178 More generally, any available musical symbol may be included
1179 separately in a markup object, as demonstrated below; an exhaustive
1180 list of these symbols and their names can be found in
1181 @ref{The Emmentaler font}.
1183 @lilypond[quote,verbatim]
1186 c'^\markup { \musicglyph #"eight" }
1188 c,8._\markup { \musicglyph #"clefs.G_change" }
1190 c2^\markup { \musicglyph #"timesig.neomensural94" }
1194 Another way of printing non-text glyphs is described in
1195 @ref{Fonts explained}. This is useful for printing braces of various
1198 The markup mode also supports diagrams for specific
1201 @lilypond[quote,verbatim]
1204 \fret-diagram-terse #"x;x;o;2;3;2;"
1207 \harp-pedal #"^-v|--ov^"
1212 \musicglyph #"accordion.discant"
1214 \raise #0.5 \musicglyph #"accordion.dot"
1215 \raise #1.5 \musicglyph #"accordion.dot"
1220 @c The accordion diagram is actually taken from a snippet.
1223 Such diagrams are documented in @ref{Instrument Specific Markup}.
1225 @cindex score inside markup
1226 @cindex markup, score inside
1228 A whole score can even be nested inside a markup object. In such a
1229 case, the nested @code{\score} block must contain a @code{\layout}
1230 block, as demonstrated here:
1232 @lilypond[quote,verbatim]
1236 \relative { c'4 d e f }
1245 An exhaustive list of music notation related commands can be found in
1251 @ref{The Emmentaler font},
1252 @ref{Fonts explained}.
1255 @file{scm/define-markup-commands.scm},
1256 @file{scm/fret-diagrams.scm},
1257 @file{scm/harp-pedals.scm}.
1262 Internals Reference:
1263 @rinternals{TextScript}.
1266 @node Multi-page markup
1267 @unnumberedsubsubsec Multi-page markup
1269 @cindex multi-page markup
1270 @cindex markup, multi-page
1271 @cindex markup text, multi-page
1272 @cindex text spread over multiple pages
1274 @funindex \markuplist
1275 @funindex \justified-lines
1276 @funindex \wordwrap-lines
1278 Although standard markup objects are not breakable, a specific syntax
1279 makes it possible to enter lines of text that can spread over multiple
1282 @lilypond[quote,verbatim]
1285 A very long text of justified lines.
1289 Another very long paragraph.
1296 This syntax accepts a list of markups, that can be
1299 the result of a markup list command,
1303 a list of markup lists.
1306 An exhaustive list of markup list commands can be found in
1307 @ref{Text markup list commands}.
1311 @ref{Text markup list commands}.
1314 @rextend{New markup list command definition}.
1317 @file{scm/define-markup-commands.scm}.
1322 Internals Reference:
1323 @rinternals{TextScript}.
1325 @funindex \markuplist
1335 This section presents the way fonts are handled, and how they may be
1340 * Single entry fonts::
1341 * Entire document fonts::
1344 @node Fonts explained
1345 @unnumberedsubsubsec Fonts explained
1348 @cindex fonts, explained
1349 @cindex braces, various sizes
1350 @cindex fonts, non-text in markup
1351 @cindex non-text fonts in markup
1353 @funindex font-interface
1355 Fonts are handled through several libraries. FontConfig is used to
1356 detect available fonts on the system; the selected fonts are rendered
1359 Music notation fonts can be described as a set of specific glyphs,
1360 ordered in several families. The following syntax allows LilyPond's
1361 various @emph{Feta} glyphs to be used directly in markup mode:
1363 @lilypond[quote,verbatim,fragment]
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:
1392 The @emph{roman} (serif) font,
1393 which defaults to LilyPond Serif (an alias of TeX Gyre Schola).
1395 The @emph{sans} font,
1396 which defaults to LilyPond Sans Serif (an alias of TeX Gyre Heros).
1398 The @emph{typewriter} (monospaced) font,
1399 which defaults to LilyPond Monospace (an alias of TeX Gyre Cursor).
1402 Each family may include different shapes and series. The following
1403 example demonstrates the ability to select alternate families, shapes,
1404 series and sizes. The value supplied to @code{font-size} is the
1405 required change from the default size.
1407 @lilypond[quote,verbatim,fragment]
1408 \override Score.RehearsalMark.font-family = #'typewriter
1409 \mark \markup "Ouverture"
1410 \override Voice.TextScript.font-shape = #'italic
1411 \override Voice.TextScript.font-series = #'bold
1412 d''2.^\markup "Allegro"
1413 \override Voice.TextScript.font-size = #-3
1418 A similar syntax may be used in markup mode; however in this case it
1419 is preferable to use the simpler syntax explained in
1420 @ref{Selecting font and font size}:
1422 @lilypond[quote,verbatim]
1426 \override #'(font-shape . italic)
1427 \override #'(font-size . 4)
1431 \override #'(font-family . typewriter)
1433 \override #'(font-series . bold)
1437 \override #'(font-family . sans)
1444 Although it is easy to switch between preconfigured fonts, it is also
1445 possible to use other fonts, as explained in the following sections:
1446 @ref{Single entry fonts} and @ref{Entire document fonts}.
1450 @ref{The Emmentaler font},
1451 @ref{Music notation inside markup},
1452 @ref{Rotating objects},
1453 @ref{Selecting font and font size},
1457 @node Single entry fonts
1458 @unnumberedsubsubsec Single entry fonts
1460 Any font that is installed on the operating system and recognized by
1461 FontConfig may be used in a score, using the following syntax:
1463 @lilypond[quote,verbatim,fragment]
1464 \override Staff.TimeSignature.font-name = #"Bitstream Charter"
1465 \override Staff.TimeSignature.font-size = #2
1469 \override #'(font-name . "Bitstream Vera Sans,sans-serif, Oblique Bold")
1470 { Vera Oblique Bold }
1474 @cindex fonts, finding available
1475 @cindex finding available fonts
1476 @cindex listing available fonts
1477 @cindex available fonts, listing
1479 @var{font-name} can be described using a comma-separated list of @q{fonts}
1480 and a white-space separated list of @q{styles}.
1481 As long as the @q{font} in the list is installed
1482 and contains requested glyph, it will be used,
1483 otherwise the @emph{next} font in the list will be used instead.
1485 @funindex show-available-fonts
1487 Running lilypond with the following option displays a list of all
1488 available fonts on the operating system:
1491 lilypond -dshow-available-fonts x
1496 @ref{Fonts explained},
1497 @ref{Entire document fonts}.
1502 @c A source file gets never installed...
1504 @c @file{lily/font-config-scheme.cc}.
1507 @node Entire document fonts
1508 @unnumberedsubsubsec Entire document fonts
1510 It is possible to change the fonts to be used as the default fonts in
1511 the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
1512 specifying them, in that order, as shown in the example below, which
1513 automatically scales the fonts with the value set for the global staff
1514 size. Similar to @ref{Single entry fonts}, it can be described using a
1515 comma-separated list of @q{fonts}. However, font @q{styles} can not be
1516 described. For an explanation of fonts, see @ref{Fonts explained}.
1518 @cindex font families, setting
1519 @cindex fonts, changing for entire document
1521 @funindex make-pango-font-tree
1523 @lilypond[verbatim,quote]
1526 (make-pango-font-tree "Times New Roman"
1527 "Nimbus Sans,Nimbus Sans L"
1529 (/ staff-height pt 20)))
1536 \typewriter typewriter. }
1540 @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},