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}.
171 @funindex \textSpannerUp
172 @funindex textSpannerUp
173 @funindex \textSpannerDown
174 @funindex textSpannerDown
175 @funindex \textSpannerNeutral
176 @funindex textSpannerNeutral
180 @code{\textSpannerUp},
181 @code{\textSpannerDown},
182 @code{\textSpannerNeutral}.
186 LilyPond is only able to handle one text spanner per voice.
190 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
191 {dynamics-text-spanner-postfix.ly}
193 @lilypondfile[verbatim,lilyquote,texidoc,doctitle]
194 {dynamics-custom-text-spanner-postfix.ly}
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
227 the syntax described 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; depending on
262 whether they are specified at the end or the middle of a bar, they
263 can be placed above the bar line or between notes. When specified at a
264 line break, the mark will be printed at the beginning of the next line.
266 @lilypond[quote,verbatim,relative=2]
276 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
277 {printing-marks-at-the-end-of-a-line.ly}
279 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
280 {aligning-marks-with-various-notation-objects.ly}
282 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
283 {printing-marks-on-every-staff.ly}
288 @ref{Rehearsal marks},
289 @ref{Formatting text},
290 @ref{Music notation inside markup},
297 @rinternals{MarkEvent},
298 @rinternals{Mark_engraver},
299 @rinternals{RehearsalMark}.
303 @unnumberedsubsubsec Separate text
305 @cindex separate text
306 @cindex text, separate
307 @cindex standalone text
308 @cindex top-level text
309 @cindex text, top-level
310 @cindex text, standalone
315 A @code{\markup} block can exist by itself, outside of any
316 @code{\score} block, as a @qq{top-level expression}. This syntax
317 is described in @ref{File structure}.
319 @lilypond[verbatim,quote]
321 Tomorrow, and tomorrow, and tomorrow...
326 This allows printing text separately from the music, which is
327 particularly useful when the input file contains several music pieces,
328 as described in @ref{Multiple scores in a book}.
330 @lilypond[quote,verbatim]
335 Tomorrow, and tomorrow, and tomorrow...
342 Separate text blocks can be spread over multiple pages,
343 making it possible to print text documents or books entirely
344 within LilyPond. This feature, and the specific syntax it
345 requires, are described in @ref{Multi-page markup}.
350 @funindex \markuplines
351 @funindex markuplines
361 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
362 {stand-alone-two-column-markup.ly}
367 @ref{Formatting text},
368 @ref{File structure},
369 @ref{Multiple scores in a book},
370 @ref{Multi-page markup}.
376 @rinternals{TextScript}.
379 @node Formatting text
380 @subsection Formatting text
382 This section presents basic and advanced text formatting,
383 using the @code{\markup} mode specific syntax.
386 * Text markup introduction::
387 * Selecting font and font size::
389 * Graphic notation inside markup::
390 * Music notation inside markup::
391 * Multi-page markup::
394 @node Text markup introduction
395 @unnumberedsubsubsec Text markup introduction
405 A @code{\markup} block is used to typeset text with an extensible
406 syntax called @qq{markup mode}.
408 @cindex markup expressions
409 @cindex expressions, markup
410 @cindex markup syntax
411 @cindex syntax, markup
413 The markup syntax is similar to LilyPond's usual syntax: a
414 @code{\markup} expression is enclosed in curly braces @code{@{
415 @dots{} @}}. A single word is regarded as a minimal expression,
416 and therefore does not need to be enclosed with braces.
418 Unlike simple @qq{quoted text} indications, @code{\markup} blocks may
419 contain nested expressions or markup commands, entered using the
420 backslash @code{\} character. Such commands only affect the first
421 following expression.
423 @lilypond[quote,verbatim,relative=2]
425 a2^\markup { poco \italic più forte }
427 d2_\markup { \italic "string. assai" }
429 b1^\markup { \bold { molto \italic agitato } }
433 @cindex special characters in markup mode
434 @cindex markup mode, special characters
435 @cindex reserved characters, printing
436 @cindex printing reserved characters
437 @cindex printing special characters
438 @cindex quoted text in markup mode
439 @cindex markup mode, quoted text
441 A @code{\markup} block may also contain quoted text strings. Such
442 strings are treated as minimal text expressions, and therefore any
443 markup command or special character (such as @code{\} and @code{#})
444 will be printed verbatim without affecting the formatting of the text.
445 Double quotation marks themselves may be printed by preceding them
448 @lilypond[quote,verbatim,relative=2]
449 a1^"\italic markup..."
450 a_\markup { \italic "... prints \"italic\" letters!" }
454 To be treated as a distinct expression, a list of words needs to be
455 enclosed with double quotes or preceded by a command. The way markup
456 expressions are defined affects how these expressions will be stacked,
457 centered and aligned; in the following example, the second
458 @code{\markup} expression is treated the same as the first one:
460 @lilypond[quote,verbatim,relative=2]
461 c1^\markup { \center-column { a bbb c } }
462 c1^\markup { \center-column { a { bbb c } } }
463 c1^\markup { \center-column { a \line { bbb c } } }
464 c1^\markup { \center-column { a "bbb c" } }
467 Markups can be stored in variables. Such variables may be
468 directly attached to notes:
470 @lilypond[quote,verbatim]
471 allegro = \markup { \bold \large Allegro }
481 An exhaustive list of @code{\markup}-specific commands can be found in
482 @ref{Text markup commands}.
487 @ref{Text markup commands}.
493 @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 @ref{Text marks}.
759 @cindex text, vertical alignment
760 @cindex vertical text alignment
769 @c QUERY Should the function of ``\null'' be clarified? rp
771 Vertical alignment is a bit more complex. As stated above, markup
772 objects can be moved as a whole; however, it is also possible to move
773 specific elements inside a markup block. In this case, the element to
774 be moved needs to be preceded with an @emph{anchor point}, that can be
775 another markup element or an invisible object. The following example
776 demonstrates these two possibilities; the last markup in this example
777 has no anchor point, and therefore is not moved.
779 @lilypond[quote,verbatim,relative=1]
782 \raise #2 { Scène 1 }
787 \lower #4 \bold { Très modéré }
791 \raise #4 \italic { Une forêt. }
796 @funindex \general-align
797 @funindex general-align
800 @funindex \translate-scaled
801 @funindex translate-scaled
803 Some commands can affect both the horizontal and vertical alignment of
804 text objects in markup mode. Any object affected by these commands
805 must be preceded with an anchor point:
807 @lilypond[quote,verbatim,relative=1]
810 \translate #'(-1 . 2) "Scène 1"
815 \general-align #Y #3.2 \bold "Très modéré"
820 \translate-scaled #'(-1 . 2) \teeny "Une forêt."
825 @cindex multi-line markup
826 @cindex markup, multi-line
827 @cindex multi-line text
828 @cindex text, multi-line
829 @cindex text in columns
830 @cindex columns, text
834 @funindex \center-column
835 @funindex center-column
837 A markup object may include several lines of text. In the following
838 example, each element or expression is placed on its own line, either
839 left-aligned or centered:
841 @lilypond[quote,verbatim]
857 @cindex centering text on the page
858 @cindex text, centering on the page
859 @cindex markup, centering on the page
864 Similarly, a list of elements or expressions may be spread to fill the
865 entire horizontal line width (if there is only one element, it will be
866 centered on the page). These expressions can, in turn, include
867 multi-line text or any other markup expression:
869 @lilypond[quote,verbatim]
872 \line { William S. Gilbert }
874 \huge \smallCaps "The Mikado"
876 \smallCaps "The Town of Titipu"
878 \line { Sir Arthur Sullivan }
886 @cindex wordwrapped text
887 @cindex justified text
888 @cindex text, justified
889 @cindex text, wordwrapped
890 @cindex markup text, wordwrapped
891 @cindex markup text, justified
898 Long text indications can also be automatically wrapped accordingly to
899 the given line width. These will be either left-aligned or justified,
900 as shown in the following example.
902 @lilypond[quote,verbatim]
905 \line \smallCaps { La vida breve }
906 \line \bold { Acto I }
908 (La escena representa el corral de una casa de
909 gitanos en el AlbaicÃn de Granada. Al fondo una
910 puerta por la que se ve el negro interior de
911 una Fragua, iluminado por los rojos resplandores
916 \line \bold { Acto II }
917 \override #'(line-width . 50)
919 (Calle de Granada. Fachada de la casa de Carmela
920 y su hermano Manuel con grandes ventanas abiertas
921 a través de las que se ve el patio
922 donde se celebra una alegre fiesta)
928 @cindex text alignment commands
929 @cindex markup text alignment commands
930 @cindex alignment, text, commands
932 An exhaustive list of text alignment commands can be found in
938 @rlearning{Moving objects}.
948 @rinternals{TextScript}.
951 @file{scm/define-markup-commands.scm}.
954 @node Graphic notation inside markup
955 @unnumberedsubsubsec Graphic notation inside markup
957 @cindex graphics, embedding
958 @cindex drawing graphic objects
959 @cindex graphic objects, drawing
960 @cindex embedding graphic objects
961 @cindex graphic objects, embedding
963 Various graphic objects may be added to a score, using markup
966 @cindex decorating text
968 @cindex text, framing
969 @cindex text, decorating
970 @cindex markup text, decorating
971 @cindex markup text, framing
977 @funindex \rounded-box
978 @funindex rounded-box
984 Some markup commands allow decoration of text elements with graphics,
985 as demonstrated in the following example.
987 @lilypond[quote,verbatim]
996 \bracket "1866 - 1925"
999 \rounded-box \bold Prelude
1004 @cindex padding around text
1005 @cindex text padding
1006 @cindex markup text padding
1008 @funindex \pad-markup
1009 @funindex pad-markup
1012 @funindex \pad-to-box
1013 @funindex pad-to-box
1014 @funindex \pad-around
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
1050 @funindex \draw-circle
1051 @funindex draw-circle
1052 @funindex \filled-box
1053 @funindex filled-box
1056 @funindex \draw-line
1058 @funindex \arrow-head
1059 @funindex arrow-head
1061 Other graphic elements or symbols may be printed without requiring any
1062 text. As with any markup expression, such objects can be combined.
1064 @lilypond[quote,verbatim]
1067 \draw-circle #4 #0.4 ##f
1068 \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
1074 \draw-line #'(0 . 4)
1075 \arrow-head #Y #DOWN ##f
1080 @cindex embedded graphics
1081 @cindex images, embedding
1082 @cindex graphics, embedding
1087 @funindex \postscript
1088 @funindex postscript
1090 Advanced graphic features include the ability to include external
1091 image files converted to the Encapsulated PostScript format
1092 (@emph{eps}), or to directly embed graphics into the input file, using
1093 native PostScript code. In such a case, it may be useful to
1094 explicitly specify the size of the drawing, as demonstrated below:
1096 @lilypond[quote,verbatim,relative=1]
1099 \epsfile #X #10 #"./context-example.eps"
1100 \with-dimensions #'(0 . 6) #'(0 . 10)
1116 An exhaustive list of graphics-specific commands can be found in
1123 @ref{Editorial annotations}.
1128 Internals Reference:
1129 @rinternals{TextScript}.
1132 @file{scm/define-markup-commands.scm},
1133 @file{scm/stencil.scm}.
1136 @node Music notation inside markup
1137 @unnumberedsubsubsec Music notation inside markup
1139 @cindex notation inside markup
1140 @cindex music inside markup
1141 @cindex markup, music notation inside
1143 Various musical notation elements may be added to a score, inside a
1146 Notes and accidentals can be entered using markup commands:
1148 @lilypond[quote,verbatim,relative=2]
1152 \note-by-number #1 #1 #1.5
1155 \natural \semiflat \flat
1156 \sesquiflat \doubleflat
1160 \natural \semisharp \sharp
1161 \sesquisharp \doublesharp
1166 Other notation objects may also be printed
1169 @lilypond[quote,verbatim,relative=1]
1176 fis_\markup { \dynamic rf }
1187 More generally, any available musical symbol may be included
1188 separately in a markup object, as demonstrated below; an exhaustive
1189 list of these symbols and their names can be found in
1190 @ref{The Feta font}.
1192 @lilypond[quote,verbatim,relative=2]
1194 c'^\markup { \musicglyph #"eight" }
1196 c,8._\markup { \musicglyph #"clefs.G_change" }
1198 c2^\markup { \musicglyph #"timesig.neomensural94" }
1201 Another way of printing non-text glyphs is described in
1202 @ref{Fonts explained}. This is useful for printing braces of various
1205 The markup mode also supports diagrams for specific
1208 @lilypond[quote,verbatim,relative=2]
1210 \fret-diagram-terse #"x;x;o;2;3;2;"
1213 \harp-pedal #"^-v|--ov^"
1218 \musicglyph #"accordion.discant"
1220 \raise #0.5 \musicglyph #"accordion.dot"
1221 \raise #1.5 \musicglyph #"accordion.dot"
1225 @c The accordion diagram is actually taken from a snippet.
1228 Such diagrams are documented in @ref{Instrument Specific Markup}.
1230 @cindex score inside markup
1231 @cindex markup, score inside
1233 A whole score can even be nested inside a markup object. In such a
1234 case, the nested @code{\score} block must contain a @code{\layout}
1235 block, as demonstrated here:
1237 @lilypond[quote,verbatim,relative=1]
1240 \relative c' { c4 d e f }
1248 An exhaustive list of music notation related commands can be found in
1255 @ref{The Feta font},
1256 @ref{Fonts explained}.
1261 Internals Reference:
1262 @rinternals{TextScript}.
1265 @file{scm/define-markup-commands.scm},
1266 @file{scm/fret-diagrams.scm},
1267 @file{scm/harp-pedals.scm}.
1270 @node Multi-page markup
1271 @unnumberedsubsubsec Multi-page markup
1273 @cindex multi-page markup
1274 @cindex markup, multi-page
1275 @cindex markup text, multi-page
1276 @cindex text spread over multiple pages
1278 @funindex \markuplines
1279 @funindex markuplines
1280 @funindex \justified-lines
1281 @funindex justified-lines
1282 @funindex \wordwrap-lines
1283 @funindex wordwrap-lines
1285 Although standard markup objects are not breakable, a specific syntax
1286 makes it possible to enter lines of text that can spread over multiple
1289 @lilypond[quote,verbatim]
1292 A very long text of justified lines.
1296 Another very long paragraph.
1303 This syntax accepts a list of markups, that can be
1306 the result of a markup list command,
1310 a list of markup lists.
1313 An exhaustive list of markup list commands can be found in
1314 @ref{Text markup list commands}.
1319 @ref{Text markup list commands},
1325 @rextend{New markup list command definition}.
1327 Internals Reference:
1328 @rinternals{TextScript}.
1331 @file{scm/define-markup-commands.scm}.
1334 @funindex \markuplines
1335 @funindex markuplines
1338 @code{\markuplines}.
1345 This section presents the way fonts are handled, and how they may be
1350 * Single entry fonts::
1351 * Entire document fonts::
1354 @node Fonts explained
1355 @unnumberedsubsubsec Fonts explained
1358 @cindex fonts, explained
1359 @cindex braces, various sizes
1360 @cindex fonts, non-text in markup
1361 @cindex non-text fonts in markup
1363 @funindex font-interface
1365 Fonts are handled through several libraries. FontConfig is used to
1366 detect available fonts on the system; the selected fonts are rendered
1369 Music notation fonts can be described as a set of specific glyphs,
1370 ordered in several families. The following syntax allows various
1371 LilyPond @code{feta} non-text fonts to be used directly in markup
1374 @lilypond[quote,verbatim,relative=2]
1377 \override #'(font-encoding . fetaBraces)
1379 \override #'(font-encoding . fetaText)
1381 \override #'(font-encoding . fetaMusic)
1382 \lookup #"noteheads.s0petrucci"
1388 However, all these glyphs except the braces of various sizes contained
1389 in @code{fetaBraces} are available using the simpler syntax described
1390 in @ref{Music notation inside markup}.
1392 When using the glyphs contained in @code{fetaBraces}, the size of the
1393 brace is specified by the numerical part of the glyph name, in
1394 arbitrary units. Any integer from @code{0} to @code{575} inclusive
1395 may be specified, @code{0} giving the smallest brace. The optimum
1396 value must be determined by trial and error. These glyphs are all
1397 left braces; right braces may be obtained by rotation, see
1398 @ref{Rotating objects}.
1400 Three families of text fonts are made available: the @emph{roman}
1401 (serif) font, that defaults to New Century Schoolbook, the @emph{sans}
1402 font and the monospaced @emph{typewriter} font -- these last two
1403 families are determined by the Pango installation.
1405 Each family may include different shapes and series. The following
1406 example demonstrates the ability to select alternate families, shapes,
1407 series and sizes. The value supplied to @code{font-size} is the
1408 required change from the default size.
1410 @lilypond[quote,verbatim,relative=2]
1411 \override Score.RehearsalMark #'font-family = #'typewriter
1412 \mark \markup "Ouverture"
1413 \override Voice.TextScript #'font-shape = #'italic
1414 \override Voice.TextScript #'font-series = #'bold
1415 d2.^\markup "Allegro"
1416 \override Voice.TextScript #'font-size = #-3
1421 A similar syntax may be used in markup mode; however in this case it
1422 is preferable to use the simpler syntax explained in
1423 @ref{Selecting font and font size}:
1425 @lilypond[quote,verbatim]
1429 \override #'(font-shape . italic)
1430 \override #'(font-size . 4)
1434 \override #'(font-family . typewriter)
1436 \override #'(font-series . bold)
1440 \override #'(font-family . sans)
1447 Although it is easy to switch between preconfigured fonts, it is also
1448 possible to use other fonts, as explained in the following sections:
1449 @ref{Single entry fonts} and @ref{Entire document fonts}.
1454 @ref{The Feta font},
1455 @ref{Music notation inside markup},
1456 @ref{Selecting font and font size},
1460 @node Single entry fonts
1461 @unnumberedsubsubsec Single entry fonts
1463 Any font that is installed on the operating system and recognized by
1464 FontConfig may be used in a score, using the following syntax:
1466 @lilypond[quote,verbatim,relative=2]
1467 \override Staff.TimeSignature #'font-name = #"Bitstream Charter"
1468 \override Staff.TimeSignature #'font-size = #2
1472 \override #'(font-name . "Vera Bold")
1477 @cindex fonts, finding available
1478 @cindex finding available fonts
1479 @cindex listing available fonts
1480 @cindex available fonts, listing
1482 @funindex show-available-fonts
1484 The following command displays a list of all available fonts on the
1488 lilypond -dshow-available-fonts x
1494 @ref{Fonts explained},
1495 @ref{Entire document fonts}.
1500 @c A source file gets never installed...
1502 @c @file{lily/font-config-scheme.cc}.
1505 @node Entire document fonts
1506 @unnumberedsubsubsec Entire document fonts
1508 It is possible to change the fonts to be used as the default fonts in
1509 the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
1510 specifying them, in that order, as shown in the example below. For an
1511 explanation of fonts, see @ref{Fonts explained}.
1513 @cindex font families, setting
1514 @cindex fonts, changing for entire document
1516 @funindex make-pango-font-tree
1518 @lilypond[verbatim,quote]
1522 (make-pango-font-tree "Times New Roman"
1525 (/ myStaffSize 20)))
1532 \typewriter typewriter. }
1536 @c we don't do Helvetica / Courier, since GS incorrectly loads
1542 @ref{Fonts explained},
1543 @ref{Single entry fonts},
1544 @ref{Selecting font and font size},