1 @c -*- coding: utf-8; mode: texinfo; -*-
3 Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
5 When revising a translation, copy the HEAD committish of the
6 version that you are working on. For details, see the Contributors'
7 Guide, node Updating translation committishes..
15 @lilypondfile[quote]{text-headword.ly}
17 This section explains how to include text (with various
18 formatting) in music scores.
21 Some text elements that are not dealt with here are discussed in other
22 specific sections: @ref{Vocal music}, @ref{Titles and headers}.
31 @subsection Writing text
33 This section introduces different ways of adding text to a score.
35 @cindex Text, other languages
36 @warning{To write accented and special text (such as characters
37 from other languages), simply insert the characters directly into
38 the LilyPond file. The file must be saved as UTF-8. For more
39 information, see @ref{Text encoding}.}
50 @unnumberedsubsubsec Text scripts
53 @cindex text items, non-empty
54 @cindex non-empty texts
57 Simple @qq{quoted text} indications may be added to a score, as
58 demonstrated in the following example. Such indications may be
59 manually placed above or below the staff, using the syntax described
60 in @ref{Direction and placement}.
62 @lilypond[quote,verbatim,relative=2]
63 a8^"pizz." g f e a4-"scherz." f
66 This syntax is actually a shorthand; more complex text formatting may be
67 added to a note by explicitly using a @code{\markup} block, as described
68 in @ref{Formatting text}.
70 @lilypond[quote,verbatim,relative=2]
71 a8^\markup { \italic pizz. } g f e
72 a4_\markup { \tiny scherz. \bold molto } f
75 By default, text indications do not influence the note spacing. However,
76 their widths can be taken into account: in the following example, the
77 first text string does not affect spacing, whereas the second one does.
79 @lilypond[quote,verbatim,relative=2]
85 In addition to text scripts, articulations can be attached to notes.
86 For more information, see @ref{Articulations and ornamentations}.
88 For more information about the relative ordering of text scripts and
89 articulations, see @rlearning{Placement of objects}.
91 @funindex \textLengthOn
92 @funindex textLengthOn
93 @funindex \textLengthOff
94 @funindex textLengthOff
98 @code{\textLengthOff}.
103 @rlearning{Placement of objects}.
106 @ref{Formatting text},
107 @ref{Direction and placement},
108 @ref{Articulations and ornamentations}.
114 @rinternals{TextScript}.
116 @cindex text outside margin
117 @cindex margin, text running over
118 @cindex text, keeping inside margin
119 @cindex lyrics, keeping inside margin
122 Checking to make sure that text scripts and lyrics are within the
123 margins requires additonal calculations. In cases where slightly faster
124 performance is desired, use
127 \override Score.PaperColumn.keep-inside-line = ##f
132 @unnumberedsubsubsec Text spanners
134 @cindex text spanners
136 Some performance indications, e.g., @notation{rallentando} or
137 @notation{accelerando}, are written as text and are extended over
138 multiple notes with dotted lines. Such objects, called
139 @qq{spanners}, may be created from one note to another using the
142 @lilypond[verbatim,quote,relative=2]
143 \override TextSpanner.bound-details.left.text = "rit."
148 @cindex text spanners, formatting
149 @cindex formatting text spanners
152 The string to be printed is set through object properties. By default
153 it is printed in italic characters, but different formatting can be
154 obtained using @code{\markup} blocks, as described in
155 @ref{Formatting text}.
157 @lilypond[quote,relative=2,verbatim]
158 \override TextSpanner.bound-details.left.text =
159 \markup { \upright "rit." }
164 The line style, as well as the text string, can be defined as an
165 object property. This syntax is described in @ref{Line styles}.
167 @funindex \textSpannerUp
168 @funindex textSpannerUp
169 @funindex \textSpannerDown
170 @funindex textSpannerDown
171 @funindex \textSpannerNeutral
172 @funindex textSpannerNeutral
176 @code{\textSpannerUp},
177 @code{\textSpannerDown},
178 @code{\textSpannerNeutral}.
182 LilyPond is only able to handle one text spanner per voice.
186 @lilypondfile[verbatim,quote,texidoc,doctitle]
187 {dynamics-text-spanner-postfix.ly}
189 @lilypondfile[verbatim,quote,texidoc,doctitle]
190 {dynamics-custom-text-spanner-postfix.ly}
196 @ref{Formatting text}.
200 @rlsr{Expressive marks}.
203 @rinternals{TextSpanner}.
207 @unnumberedsubsubsec Text marks
212 @cindex text on bar line
213 @cindex coda on bar line
214 @cindex segno on bar line
215 @cindex fermata on bar line
216 @cindex bar lines, symbols on
223 Various text elements may be added to a score using the syntax described
224 in @ref{Rehearsal marks}:
226 @c \mark needs to be placed on a separate line (it's not
227 @c attached to an object like \markup is). -vv
229 @lilypond[verbatim,quote,relative=2]
235 This syntax makes it possible to put any text on a bar line;
236 more complex text formatting may be added using a @code{\markup}
237 block, as described in @ref{Formatting text}:
239 @lilypond[quote,verbatim,relative=1]
241 \mark \markup { \italic { colla parte } }
247 This syntax also allows to print special signs, like coda, segno
248 or fermata, by specifying the appropriate symbol name as explained in
249 @ref{Music notation inside markup}:
251 @lilypond[quote,verbatim,relative=2]
253 \mark \markup { \musicglyph #"scripts.ufermata" }
258 Such objects are only typeset above the top staff of the score;
259 depending on whether they are specified at the end or the middle of a
260 bar, they can be placed above the bar line or between notes. When
261 specified at a line break, the mark will be printed at the beginning of
264 @lilypond[quote,verbatim,relative=2,ragged-right]
271 @funindex \markLengthOn
272 @funindex markLengthOn
273 @funindex \markLengthOff
274 @funindex markLengthOff
277 @code{\markLengthOn},
278 @code{\markLengthOff}.
283 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
284 {printing-marks-at-the-end-of-a-line.ly}
286 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
287 {printing-marks-on-every-staff.ly}
291 @ref{Rehearsal marks},
292 @ref{Formatting text},
293 @ref{Music notation inside markup},
300 @rinternals{MarkEvent},
301 @rinternals{Mark_engraver},
302 @rinternals{RehearsalMark}.
306 @unnumberedsubsubsec Separate text
308 @cindex separate text
309 @cindex text, separate
310 @cindex standalone text
311 @cindex top-level text
312 @cindex text, top-level
313 @cindex text, standalone
318 A @code{\markup} block can exist by itself, outside of any
319 @code{\score} block, as a @qq{top-level expression}. This syntax
320 is described in @ref{File structure}.
322 @lilypond[verbatim,quote]
324 Tomorrow, and tomorrow, and tomorrow...
329 This allows printing text separately from the music, which is
330 particularly useful when the input file contains several music pieces,
331 as described in @ref{Multiple scores in a book}.
333 @lilypond[quote,verbatim]
338 Tomorrow, and tomorrow, and tomorrow...
345 Separate text blocks can be spread over multiple pages,
346 making it possible to print text documents or books entirely
347 within LilyPond. This feature, and the specific syntax it
348 requires, are described in @ref{Multi-page markup}.
353 @funindex \markuplist
364 @lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
365 {stand-alone-two-column-markup.ly}
369 @ref{Formatting text},
370 @ref{File structure},
371 @ref{Multiple scores in a book},
372 @ref{Multi-page markup}.
378 @rinternals{TextScript}.
381 @node Formatting text
382 @subsection Formatting text
384 This section presents basic and advanced text formatting,
385 using the @code{\markup} mode specific syntax.
388 * Text markup introduction::
389 * Selecting font and font size::
391 * Graphic notation inside markup::
392 * Music notation inside markup::
393 * Multi-page markup::
396 @node Text markup introduction
397 @unnumberedsubsubsec Text markup introduction
407 A @code{\markup} block is used to typeset text with an extensible
408 syntax called @qq{markup mode}.
410 @cindex markup expressions
411 @cindex expressions, markup
412 @cindex markup syntax
413 @cindex syntax, markup
415 The markup syntax is similar to LilyPond's usual syntax: a
416 @code{\markup} expression is enclosed in curly braces
417 @code{@{@dots{} @}}. A single word is regarded as a minimal expression,
418 and therefore does not need to be enclosed with braces.
420 Unlike simple @qq{quoted text} indications, @code{\markup} blocks may
421 contain nested expressions or markup commands, entered using the
422 backslash @code{\} character. Such commands only affect the first
423 following expression.
425 @lilypond[quote,verbatim,relative=2]
427 a2^\markup { poco \italic più forte }
429 d2_\markup { \italic "string. assai" }
431 b1^\markup { \bold { molto \italic agitato } }
435 @cindex special characters in markup mode
436 @cindex markup mode, special characters
437 @cindex reserved characters, printing
438 @cindex printing reserved characters
439 @cindex printing special characters
440 @cindex quoted text in markup mode
441 @cindex markup mode, quoted text
443 A @code{\markup} block may also contain quoted text strings. Such
444 strings are treated as minimal text expressions, and therefore any
445 markup command or special character (such as @code{\} and@tie{}@code{#})
446 will be printed verbatim without affecting the formatting of the text.
447 Double quotation marks themselves may be printed by preceding them
450 @lilypond[quote,verbatim,relative=2]
451 a1^"\italic markup..."
452 a_\markup { \italic "... prints \"italic\" letters!" }
456 To be treated as a distinct expression, a list of words needs to be
457 enclosed with double quotes or preceded by a command. The way markup
458 expressions are defined affects how these expressions will be stacked,
459 centered and aligned; in the following example, the second
460 @code{\markup} expression is treated the same as the first one:
462 @lilypond[quote,verbatim,relative=2]
463 c1^\markup { \center-column { a bbb c } }
464 c1^\markup { \center-column { a { bbb c } } }
465 c1^\markup { \center-column { a \line { bbb c } } }
466 c1^\markup { \center-column { a "bbb c" } }
469 Markups can be stored in variables. Such variables may be
470 directly attached to notes:
472 @lilypond[quote,verbatim]
473 allegro = \markup { \bold \large Allegro }
483 An exhaustive list of @code{\markup}-specific commands can be found in
484 @ref{Text markup commands}.
488 @ref{Text markup commands}.
494 @file{scm/markup.scm}.
497 Syntax errors for markup mode can be confusing.
500 @node Selecting font and font size
501 @unnumberedsubsubsec Selecting font and font size
503 @cindex font switching
504 @cindex changing fonts
505 @cindex switching fonts
514 Basic font switching is supported in markup mode:
516 @lilypond[quote,verbatim,relative=2]
519 \italic { non troppo \underline Vivo }
522 d,_\markup { \italic quasi \smallCaps Tromba }
529 @funindex \abs-fontsize
539 The font size can be altered, relative to the global staff size, in a
540 number of different ways
542 It can be set to predefined size,
544 @lilypond[quote,verbatim,relative=2]
545 b1_\markup { \huge Sinfonia }
546 b1^\markup { \teeny da }
547 b1-\markup { \normalsize camera }
550 It can be set relative to its previous value,
552 @lilypond[quote,verbatim,relative=2]
553 b1_\markup { \larger Sinfonia }
554 b1^\markup { \smaller da }
555 b1-\markup { \magnify #0.6 camera }
558 It can be increased or decreased relative to the value set by the
561 @lilypond[quote,verbatim,relative=2]
562 b1_\markup { \fontsize #-2 Sinfonia }
563 b1^\markup { \fontsize #1 da }
564 b1-\markup { \fontsize #3 camera }
567 It can also be set to a fixed point-size, regardless of the global staff
570 @lilypond[quote,verbatim,relative=2]
571 b1_\markup { \abs-fontsize #20 Sinfonia }
572 b1^\markup { \abs-fontsize #8 da }
573 b1-\markup { \abs-fontsize #14 camera }
576 If the text includes spaces, then it is best to put it all inside quote
577 marks, so that the size of each space is appropriate for the size of the
580 @lilypond[quote,verbatim]
581 \markup \fontsize #6 \bold { Sinfonia da camera }
582 \markup \fontsize #6 \bold { "Sinfonia da camera" }
592 @funindex \normal-size-super
593 @funindex normal-size-super
595 Text may be printed as subscript or superscript. By default these are
596 printed in a smaller size, but a normal size can be used as well:
598 @lilypond[quote,verbatim]
601 \line { 1 \super st movement }
602 \line { 1 \normal-size-super st movement
603 \sub { (part two) } }
608 @cindex font families
610 The markup mode provides an easy way to select alternate font
611 families. The default serif font, of roman type, is automatically
612 selected unless specified otherwise; on the last line of the following
613 example, there is no difference between the first and the second word.
615 @lilypond[quote,verbatim]
618 \line { Act \number 1 }
619 \line { \sans { Scene I. } }
620 \line { \typewriter { Verona. An open place. } }
621 \line { Enter \roman Valentine and Proteus. }
627 Some of these font families, used for specific items such as numbers
628 or dynamics, do not provide all characters, as mentioned in
629 @ref{New dynamic marks} and @ref{Manual repeat marks}.
631 @c \concat is actually documented in Align (it is not
632 @c a font-switching command). But we need it here. -vv
634 When used inside a word, some font-switching or formatting commands
635 may produce an unwanted blank space. This can easily be solved by
636 concatenating the text elements together:
638 @lilypond[quote,verbatim]
642 \concat { 1 \super st }
646 \concat { \dynamic p , }
647 \italic { con dolce espressione }
653 An exhaustive list of font switching commands and custom font usage
654 commands can be found in @ref{Font}.
656 Defining custom font sets is also possible, as explained in
665 @funindex \normalsize
691 @ref{New dynamic marks},
692 @ref{Manual repeat marks},
696 @file{scm/define-markup-commands.scm}.
702 @rinternals{TextScript}.
705 Using the font sizing commands @code{\teeny}, @code{\tiny},
706 @code{\small}, @code{\normalsize}, @code{\large}, and
707 @code{\huge} will lead to inconsistent line spacing compared to
708 using @code{\fontsize}.
712 @unnumberedsubsubsec Text alignment
714 @cindex text, aligning
715 @cindex aligning text
716 @cindex aligning markup text
717 @cindex aligning markups
718 @cindex markups, aligning
719 @cindex markup text, aligning
721 This subsection discusses how to place text in markup mode. Markup
722 objects can also be moved as a whole, using the syntax described in
723 @rlearning{Moving objects}.
725 @c Padding commands should be mentioned on this page, but
726 @c most of these require \box to be more clearly illustrated. -vv
728 @cindex text, horizontal alignment
729 @cindex horizontal text alignment
731 @funindex \left-align
733 @funindex \center-align
734 @funindex center-align
735 @funindex \right-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,relative=2]
745 d-\markup { \left-align poco }
747 d-\markup { \center-align { poco } }
749 d-\markup { \right-align poco }
755 Horizontal alignment may be fine-tuned using a numeric value:
757 @lilypond[quote,verbatim,relative=2]
758 a1-\markup { \halign #-1 poco }
760 a,-\markup { \halign #0 poco }
762 a,-\markup { \halign #0.5 poco }
764 a,-\markup { \halign #2 poco }
768 Some objects may have alignment procedures of their own, and therefore
769 are not affected by these commands. It is possible to move such
770 markup objects as a whole, as shown for instance in
773 @cindex text, vertical alignment
774 @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,relative=1]
796 \raise #2 { Scène 1 }
801 \lower #4 \bold { Très modéré }
805 \raise #4 \italic { Une forêt. }
810 @funindex \general-align
811 @funindex general-align
814 @funindex \translate-scaled
815 @funindex translate-scaled
817 Some commands can affect both the horizontal and vertical alignment of
818 text objects in markup mode. Any object affected by these commands
819 must be preceded with an anchor point:
821 @lilypond[quote,verbatim,relative=1]
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."
839 @cindex multi-line markup
840 @cindex markup, multi-line
841 @cindex multi-line text
842 @cindex text, multi-line
843 @cindex text in columns
844 @cindex columns, text
848 @funindex \center-column
849 @funindex center-column
851 A markup object may include several lines of text. In the following
852 example, each element or expression is placed on its own line, either
853 left-aligned or centered:
855 @lilypond[quote,verbatim]
871 @cindex centering text on the page
872 @cindex text, centering on the page
873 @cindex markup, centering on the page
878 Similarly, a list of elements or expressions may be spread to fill the
879 entire horizontal line width (if there is only one element, it will be
880 centered on the page). These expressions can, in turn, include
881 multi-line text or any other markup expression:
883 @lilypond[quote,verbatim]
886 \line { William S. Gilbert }
888 \huge \smallCaps "The Mikado"
890 \smallCaps "The Town of Titipu"
892 \line { Sir Arthur Sullivan }
900 @cindex wordwrapped text
901 @cindex justified text
902 @cindex text, justified
903 @cindex text, wordwrapped
904 @cindex markup text, wordwrapped
905 @cindex markup text, justified
912 Long text indications can also be automatically wrapped accordingly to
913 the given line width. These will be either left-aligned or justified,
914 as shown in the following example.
916 @lilypond[quote,verbatim]
919 \line \smallCaps { La vida breve }
920 \line \bold { Acto I }
922 (La escena representa el corral de una casa de
923 gitanos en el AlbaicÃn de Granada. Al fondo una
924 puerta por la que se ve el negro interior de
925 una Fragua, iluminado por los rojos resplandores
930 \line \bold { Acto II }
931 \override #'(line-width . 50)
933 (Calle de Granada. Fachada de la casa de Carmela
934 y su hermano Manuel con grandes ventanas abiertas
935 a través de las que se ve el patio
936 donde se celebra una alegre fiesta)
942 @cindex text alignment commands
943 @cindex markup text alignment commands
944 @cindex alignment, text, commands
946 An exhaustive list of text alignment commands can be found in
951 @rlearning{Moving objects}.
958 @file{scm/define-markup-commands.scm}.
964 @rinternals{TextScript}.
967 @node Graphic notation inside markup
968 @unnumberedsubsubsec Graphic notation inside markup
970 @cindex graphics, embedding
971 @cindex drawing graphic objects
972 @cindex graphic objects, drawing
973 @cindex embedding graphic objects
974 @cindex graphic objects, embedding
976 Various graphic objects may be added to a score, using markup
979 @cindex decorating text
981 @cindex text, framing
982 @cindex text, decorating
983 @cindex markup text, decorating
984 @cindex markup text, framing
990 @funindex \rounded-box
991 @funindex rounded-box
997 Some markup commands allow decoration of text elements with graphics,
998 as demonstrated in the following example.
1000 @lilypond[quote,verbatim]
1001 \markup \fill-line {
1009 \bracket "1866 - 1925"
1012 \rounded-box \bold Prelude
1017 @cindex padding around text
1018 @cindex text padding
1019 @cindex markup text padding
1021 @funindex \pad-markup
1022 @funindex pad-markup
1025 @funindex \pad-to-box
1026 @funindex pad-to-box
1027 @funindex \pad-around
1028 @funindex pad-around
1030 Some commands may require an increase in the padding around the text;
1031 this is achieved with some markup commands exhaustively described in
1034 @lilypond[quote,verbatim]
1035 \markup \fill-line {
1037 \box "Charles Ives (1874 - 1954)"
1039 \box \pad-markup #2 "THE UNANSWERED QUESTION"
1040 \box \pad-x #8 "A Cosmic Landscape"
1047 \box \pad-to-box #'(-5 . 20) #'(0 . 5)
1048 \bold "Largo to Presto"
1051 "String quartet keeps very even time,
1052 Flute quartet keeps very uneven time."
1056 @cindex graphic notation
1057 @cindex symbols, non-musical
1058 @cindex non-musical symbols
1059 @cindex notation, graphic
1063 @funindex \draw-circle
1064 @funindex draw-circle
1065 @funindex \filled-box
1066 @funindex filled-box
1069 @funindex \draw-line
1071 @funindex \arrow-head
1072 @funindex arrow-head
1074 Other graphic elements or symbols may be printed without requiring any
1075 text. As with any markup expression, such objects can be combined.
1077 @lilypond[quote,verbatim]
1080 \draw-circle #4 #0.4 ##f
1081 \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
1087 \draw-line #'(0 . 4)
1088 \arrow-head #Y #DOWN ##f
1093 @cindex embedded graphics
1094 @cindex images, embedding
1095 @cindex graphics, embedding
1100 @funindex \postscript
1101 @funindex postscript
1103 Advanced graphic features include the ability to include external
1104 image files converted to the Encapsulated PostScript format
1105 (@emph{eps}), or to directly embed graphics into the input file, using
1106 native PostScript code. In such a case, it may be useful to
1107 explicitly specify the size of the drawing, as demonstrated below:
1109 @lilypond[quote,verbatim,relative=1]
1112 \epsfile #X #10 #"./context-example.eps"
1113 \with-dimensions #'(0 . 6) #'(0 . 10)
1129 An exhaustive list of graphics-specific commands can be found in
1136 @ref{Editorial annotations},
1140 @file{scm/define-markup-commands.scm},
1141 @file{scm/stencil.scm}.
1146 Internals Reference:
1147 @rinternals{TextScript}.
1150 @node Music notation inside markup
1151 @unnumberedsubsubsec Music notation inside markup
1153 @cindex notation inside markup
1154 @cindex music inside markup
1155 @cindex markup, music notation inside
1157 Various musical notation elements may be added to a score, inside a
1160 Notes and accidentals can be entered using markup commands:
1162 @lilypond[quote,verbatim,relative=2]
1166 \note-by-number #1 #1 #1.5
1169 \natural \semiflat \flat
1170 \sesquiflat \doubleflat
1174 \natural \semisharp \sharp
1175 \sesquisharp \doublesharp
1180 Other notation objects may also be printed
1183 @lilypond[quote,verbatim,relative=1]
1185 ees\finger \markup \tied-lyric #"4~1"
1186 fis_\markup { \dynamic rf }
1197 More generally, any available musical symbol may be included
1198 separately in a markup object, as demonstrated below; an exhaustive
1199 list of these symbols and their names can be found in
1200 @ref{The Feta font}.
1202 @lilypond[quote,verbatim,relative=2]
1204 c'^\markup { \musicglyph #"eight" }
1206 c,8._\markup { \musicglyph #"clefs.G_change" }
1208 c2^\markup { \musicglyph #"timesig.neomensural94" }
1211 Another way of printing non-text glyphs is described in
1212 @ref{Fonts explained}. This is useful for printing braces of various
1215 The markup mode also supports diagrams for specific
1218 @lilypond[quote,verbatim,relative=2]
1220 \fret-diagram-terse #"x;x;o;2;3;2;"
1223 \harp-pedal #"^-v|--ov^"
1228 \musicglyph #"accordion.discant"
1230 \raise #0.5 \musicglyph #"accordion.dot"
1231 \raise #1.5 \musicglyph #"accordion.dot"
1235 @c The accordion diagram is actually taken from a snippet.
1238 Such diagrams are documented in @ref{Instrument Specific Markup}.
1240 @cindex score inside markup
1241 @cindex markup, score inside
1243 A whole score can even be nested inside a markup object. In such a
1244 case, the nested @code{\score} block must contain a @code{\layout}
1245 block, as demonstrated here:
1247 @lilypond[quote,verbatim,relative=1]
1250 \relative { c'4 d e f }
1258 An exhaustive list of music notation related commands can be found in
1264 @ref{The Feta font},
1265 @ref{Fonts explained}.
1268 @file{scm/define-markup-commands.scm},
1269 @file{scm/fret-diagrams.scm},
1270 @file{scm/harp-pedals.scm}.
1275 Internals Reference:
1276 @rinternals{TextScript}.
1279 @node Multi-page markup
1280 @unnumberedsubsubsec Multi-page markup
1282 @cindex multi-page markup
1283 @cindex markup, multi-page
1284 @cindex markup text, multi-page
1285 @cindex text spread over multiple pages
1287 @funindex \markuplist
1288 @funindex markuplist
1289 @funindex \justified-lines
1290 @funindex justified-lines
1291 @funindex \wordwrap-lines
1292 @funindex wordwrap-lines
1294 Although standard markup objects are not breakable, a specific syntax
1295 makes it possible to enter lines of text that can spread over multiple
1298 @lilypond[quote,verbatim]
1301 A very long text of justified lines.
1305 Another very long paragraph.
1312 This syntax accepts a list of markups, that can be
1315 the result of a markup list command,
1319 a list of markup lists.
1322 An exhaustive list of markup list commands can be found in
1323 @ref{Text markup list commands}.
1327 @ref{Text markup list commands}.
1330 @rextend{New markup list command definition}.
1333 @file{scm/define-markup-commands.scm}.
1338 Internals Reference:
1339 @rinternals{TextScript}.
1341 @funindex \markuplist
1342 @funindex markuplist
1352 This section presents the way fonts are handled, and how they may be
1357 * Single entry fonts::
1358 * Entire document fonts::
1361 @node Fonts explained
1362 @unnumberedsubsubsec Fonts explained
1365 @cindex fonts, explained
1366 @cindex braces, various sizes
1367 @cindex fonts, non-text in markup
1368 @cindex non-text fonts in markup
1370 @funindex font-interface
1372 Fonts are handled through several libraries. FontConfig is used to
1373 detect available fonts on the system; the selected fonts are rendered
1376 Music notation fonts can be described as a set of specific glyphs,
1377 ordered in several families. The following syntax allows various
1378 LilyPond @code{feta} non-text fonts to be used directly in markup
1381 @lilypond[quote,verbatim,relative=2]
1384 \override #'(font-encoding . fetaBraces)
1386 \override #'(font-encoding . fetaText)
1388 \override #'(font-encoding . fetaMusic)
1389 \lookup #"noteheads.s0petrucci"
1395 However, all these glyphs except the braces of various sizes contained
1396 in @code{fetaBraces} are available using the simpler syntax described
1397 in @ref{Music notation inside markup}.
1399 When using the glyphs contained in @code{fetaBraces}, the size of the
1400 brace is specified by the numerical part of the glyph name, in
1401 arbitrary units. Any integer from @code{0} to @code{575} inclusive
1402 may be specified, @code{0} giving the smallest brace. The optimum
1403 value must be determined by trial and error. These glyphs are all
1404 left braces; right braces may be obtained by rotation, see
1405 @ref{Rotating objects}.
1407 Three families of text fonts are made available: the @emph{roman}
1408 (serif) font, that defaults to New Century Schoolbook, the
1409 @emph{sans} font and the monospaced @emph{typewriter} font -- these
1410 last two families are determined by the Pango installation.
1412 @warning{There are no default fonts associated with the @emph{sans}
1413 and @emph{typewriter} font-families. An input file that specifies
1414 either of these can lead to different output on different computers.
1415 To ensure consistent output among multiple platforms, fonts must be
1416 specified by name, and those fonts must be available on any system
1417 that processes the file. See @ref{Single entry fonts} and
1418 @ref{Entire document fonts}.}
1420 Each family may include different shapes and series. The following
1421 example demonstrates the ability to select alternate families, shapes,
1422 series and sizes. The value supplied to @code{font-size} is the
1423 required change from the default size.
1425 @lilypond[quote,verbatim,relative=2]
1426 \override Score.RehearsalMark.font-family = #'typewriter
1427 \mark \markup "Ouverture"
1428 \override Voice.TextScript.font-shape = #'italic
1429 \override Voice.TextScript.font-series = #'bold
1430 d2.^\markup "Allegro"
1431 \override Voice.TextScript.font-size = #-3
1436 A similar syntax may be used in markup mode; however in this case it
1437 is preferable to use the simpler syntax explained in
1438 @ref{Selecting font and font size}:
1440 @lilypond[quote,verbatim]
1444 \override #'(font-shape . italic)
1445 \override #'(font-size . 4)
1449 \override #'(font-family . typewriter)
1451 \override #'(font-series . bold)
1455 \override #'(font-family . sans)
1462 Although it is easy to switch between preconfigured fonts, it is also
1463 possible to use other fonts, as explained in the following sections:
1464 @ref{Single entry fonts} and @ref{Entire document fonts}.
1468 @ref{The Feta font},
1469 @ref{Music notation inside markup},
1470 @ref{Rotating objects},
1471 @ref{Selecting font and font size},
1475 @node Single entry fonts
1476 @unnumberedsubsubsec Single entry fonts
1478 Any font that is installed on the operating system and recognized by
1479 FontConfig may be used in a score, using the following syntax:
1481 @lilypond[quote,verbatim,relative=2]
1482 \override Staff.TimeSignature.font-name = #"Bitstream Charter"
1483 \override Staff.TimeSignature.font-size = #2
1487 \override #'(font-name . "Vera Bold")
1492 @cindex fonts, finding available
1493 @cindex finding available fonts
1494 @cindex listing available fonts
1495 @cindex available fonts, listing
1497 @funindex show-available-fonts
1499 Running lilypond with the following option displays a list of all
1500 available fonts on the operating system:
1503 lilypond -dshow-available-fonts x
1508 @ref{Fonts explained},
1509 @ref{Entire document fonts}.
1514 @c A source file gets never installed...
1516 @c @file{lily/font-config-scheme.cc}.
1519 @node Entire document fonts
1520 @unnumberedsubsubsec Entire document fonts
1522 It is possible to change the fonts to be used as the default fonts in
1523 the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
1524 specifying them, in that order, as shown in the example below, which
1525 automatically scales the fonts with the value set for the global staff
1526 size. For an explanation of fonts, see @ref{Fonts explained}.
1528 @cindex font families, setting
1529 @cindex fonts, changing for entire document
1531 @funindex make-pango-font-tree
1533 @lilypond[verbatim,quote]
1536 (make-pango-font-tree "Times New Roman"
1539 (/ staff-height pt 20)))
1546 \typewriter typewriter. }
1550 @c we don't do Helvetica / Courier, since GS incorrectly loads
1555 @ref{Fonts explained},
1556 @ref{Single entry fonts},
1557 @ref{Selecting font and font size},