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. See TRANSLATION for details.
14 @lilypondfile[quote]{text-headword.ly}
16 This section explains how to include text (with various
17 formatting) in music scores.
20 Some text elements that are not dealt with here are discussed in other
21 specific sections: @ref{Vocal music}, @ref{Titles and headers}.
24 @cindex Text, other languages
25 @warning{To write accented and special text (such as characters
26 from other languages), simply insert the characters directly into
27 the LilyPond file. The file must be saved as UTF-8. For more
28 information, see @ref{Text encoding}.}
38 @subsection Writing text
40 This section introduces different ways of adding text to a score.
51 @subsubsection Text scripts
54 @cindex text items, non-empty
55 @cindex non-empty texts
58 Simple @q{quoted text} indications may be added
59 to a score, as demonstrated in the following example.
60 Such indications can be manually placed
61 above or below the staff, using the
62 syntax described in @ref{Direction and
65 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
66 d8^"pizz." e f g a4-"scherz." f
69 This syntax is actually a shorthand; more complex text
70 formatting may be added to a note by explicitly using a
71 @code{\markup} block, as described in @ref{Formatting text}.
73 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
74 d8^\markup { \italic pizz. } e f g
75 a4_\markup { \tiny scherz. \bold molto } f
78 By default, text indications do not influence the note spacing.
79 However, their widths can be taken into account:
80 in the following example, the first text string does not affect
81 spacing, whereas the second one does.
83 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
91 @funindex \textLengthOn
93 @funindex \textLengthOff
99 Notation Reference: @ref{Formatting text},
100 @ref{Direction and placement}.
105 Internals Reference: @rinternals{TextScript}.
109 Checking to make sure that text scripts and lyrics are within the
110 margins is a relatively large computational task. To speed up
111 processing, LilyPond does not perform such calculations by
112 default; to enable it, use
115 \override Score.PaperColumn #'keep-inside-line = ##t
120 @subsubsection Text spanners
122 @cindex Text spanners
124 Some performance indications, e.g., @notation{rallentando} or
125 @notation{accelerando}, are written as text and are extended over
126 multiple notes with dotted lines.
127 Such objects, called @q{spanners}, may be created
128 from one note to another using the following syntax:
130 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
131 \override TextSpanner #'bound-details #'left #'text = "rit."
137 The string to be printed is set through
138 object properties. By default it is printed in italic characters,
139 but different formatting can be obtained using
140 @code{\markup} blocks, as described in @ref{Formatting text}.
142 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
143 \override TextSpanner #'bound-details #'left #'text =
144 \markup { \upright "rit." }
149 The line style, as well as the text string, can be defined as an
150 object property. This syntax is described in @ref{Line styles}.
154 @funindex textSpannerUp
155 @code{\textSpannerUp},
156 @funindex textSpannerDown
157 @code{\textSpannerDown},
158 @funindex textSpannerNeutral
159 @code{\textSpannerNeutral}
163 Notation Reference: @ref{Line styles}.
168 Internals Reference: @rinternals{TextSpanner}.
172 @subsubsection Text marks
174 @cindex coda on bar line
175 @cindex segno on bar line
176 @cindex fermata on bar line
177 @cindex bar lines, symbols on
180 Various text elements may be added to a score using
181 the syntax described in @ref{Rehearsal marks}:
183 @c \mark needs to be placed on a separate line (it's not
184 @c attached to an object like \markup is). -vv
186 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
192 This syntax makes it possible to put any text on a bar line;
193 more complex text formatting may be added using a @code{\markup}
194 block, as described in @ref{Formatting text}. This can be used to print
195 signs like coda, segno or fermata, by specifying the appropriate
198 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
200 \mark \markup { \musicglyph #"scripts.ufermata" }
205 Such objects are only typeset above the top staff of the score; depending on
206 whether they are specified at the end or the middle of a bar, they
207 can be placed above the bar line or between notes. When specified at the
208 beginning of a score or at a line break, marks will be printed at
209 the beginning of the line (the next line, in case of a line break).
211 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
221 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
222 {printing-marks-at-the-end-of-a-line-or-a-score.ly}
224 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
225 {aligning-marks-with-various-notation-objects.ly}
227 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
228 {printing-marks-on-every-staff.ly}
232 Notation Reference: @ref{Rehearsal marks},
233 @ref{Formatting text}, @ref{The Feta font}.
238 Internals Reference: @rinternals{RehearsalMark}.
241 @c To be removed when Issue 69 in the tracker gets fixed. -vv
243 If a mark is entered at the end of the last bar of the score (where
244 there is no next line), then the mark will not be printed at
248 @subsubsection Separate text
250 @cindex separate text
251 @cindex standalone text
252 @cindex top-level text
253 @cindex text, standalone
256 A @code{\markup} block can exist by itself, outside of any
257 any @code{\score} block, as a @qq{top-level
258 expression}. This syntax is described in @ref{File structure}.
260 @lilypond[verbatim,quote]
262 Tomorrow, and tomorrow, and tomorrow...
267 This allows printing text separately
268 from the music, which is particularly
269 useful when the input file contains
270 several music pieces, as described in
271 @ref{Multiple scores in a book}.
273 @lilypond[quote,ragged-right,verbatim]
278 Tomorrow, and tomorrow, and tomorrow...
285 Using a specific syntax, text blocks can be spread
286 over multiple pages, making possible to print
287 text documents or books (and therefore to
288 use LilyPond as a word processor). This syntax is described in
289 @ref{Multi-page markup}.
294 @funindex \markuplines
300 TODO: add convenient snippets in input/new -vv
305 Notation Reference: @ref{Formatting text},
306 @ref{File structure},
307 @ref{Multiple scores in a book},
308 @ref{Multi-page markup}.
313 Internals Reference: @rinternals{TextScript}.
316 @node Formatting text
317 @subsection Formatting text
319 This section presents basic and advanced text formatting,
320 using the @code{\markup} mode specific syntax.
323 * Text markup introduction::
324 * Selecting font and font size::
326 * Graphic notation inside markup::
327 * Music notation inside markup::
328 * Multi-page markup::
331 @node Text markup introduction
332 @subsubsection Text markup introduction
340 A @code{\markup} block is used to typeset text with an extensible
341 specific syntax called @qq{markup mode}.
343 @cindex markup expressions
344 @cindex markup syntax
346 The markup syntax is similar to LilyPond's usual syntax: a
347 @code{\markup} expression is enclosed in curly braces @code{@{
348 @dots{} @}}. A single word is regarded as a minimal expression,
349 and therefore does not need to be enclosed with braces.
351 Unlike simple @q{quoted text} indications, @code{\markup} blocks
352 may contain nested expressions or specific commands,
353 entered using the backslash @code{\} character.
354 Such commands only affect the first following expression.
356 @lilypond[quote,verbatim,fragment,relative=1]
358 a2^\markup { poco \italic più forte }
360 d2_\markup { \italic "string. assai" }
362 b1^\markup { \bold { molto \italic agitato } }
366 @cindex special characters in markup mode
367 @cindex markup mode, special characters
368 @cindex reserved characters, printing
369 @cindex printing special characters
370 @cindex quoted text in markup mode
372 A @code{\markup} block may also contain quoted text strings.
373 Such strings are treated as minimal text expressions, and
374 therefore any markup command or special character (such as
375 @code{\} and @code{#}) will be printed verbatim without affecting
376 the formatting of the text. This syntax even allows to print
377 double quotation marks, by preceding them with backslashes
379 @lilypond[quote,verbatim,fragment,relative=1]
380 d1^"\italic markup..."
381 d_\markup \italic "... prints \"italic\" letters!"
385 The way markup expressions are defined affects
386 how these expressions will be stacked, centered and aligned
387 when using the commands explained in @ref{Text alignment}.
389 @lilypond[quote,verbatim,fragment,relative=1]
390 c1^\markup { \column { a bbbb \line { c d } } }
391 c1^\markup { \center-column { a bbbb c } }
392 c1^\markup { \line { a b c } }
395 Lists of words that are not enclosed with double quotes
396 or preceded by a command are not treated as a distinct
397 expression. In the following example, the first two
398 @code{\markup} expressions are equivalent:
400 @lilypond[quote,verbatim,fragment,relative=1]
401 c1^\markup { \center-column { a bbb c } }
402 c1^\markup { \center-column { a { bbb c } } }
403 c1^\markup { \center-column { a \line { bbb c } } }
407 Markups can be stored in variables. Such variables may be
408 directly attached to notes:
410 @lilypond[quote,verbatim]
411 allegro = \markup { \bold \large Allegro }
421 An exhaustive list of @code{\markup}-specific commands can be found in
422 @ref{Text markup commands}.
427 This manual: @ref{Text markup commands}.
432 Internals Reference: @rinternals{TextScript}.
434 Init files: @file{scm/@/new@/-markup@/.scm}.
439 Syntax errors for markup mode can be confusing.
442 @node Selecting font and font size
443 @subsubsection Selecting font and font size
445 @cindex font switching
450 Basic font switching is supported in markup mode:
452 @lilypond[quote,verbatim,relative=2]
456 \italic { non troppo \underline Vivo }
459 d,_\markup { \italic quasi \smallCaps Tromba }
472 The size of the characters can also be altered in different ways:
475 the font size can be defined to an absolute value,
478 predefined commands allow to easily select standard sizes,
481 the font size can also be changed relatively to its previous value.
485 The following example demonstrates these three methods:
487 @lilypond[quote,verbatim,relative=2]
489 f1^\markup { \fontsize #5 Sinfonia }
498 \magnify #0.6 { e sentimento } )
509 Text may be printed as subscript or superscript. By default
510 these are printed in a smaller size, but a normal size can be used as well:
512 @lilypond[quote,verbatim]
515 \line { 1 \super st movement }
516 \line { 1 \normal-size-super st movement
517 \sub { (part two) } }
522 @cindex font families
524 The markup mode provides an easy way to select alternate
525 font families. The default serif font, of roman type, is
526 automatically selected unless specified otherwise: on the
527 last line of the following example, there is no difference
528 between the first and the second word.
530 @lilypond[quote,verbatim]
533 \line { Act \number 1 }
534 \line { \sans { Scene I. } }
535 \line { \typewriter { Verona. An open place. } }
536 \line { Enter \roman Valentine and Proteus. }
542 Some of these font families, used for specific items
543 such as numbers or dynamics, do not provide all
544 characters, as mentioned in @ref{New dynamic marks} and
545 @ref{Manual repeat marks}.
547 @c \concat is actually documented in Align (it is not
548 @c a font-switching command). But we need it here. -vv
550 When used inside a word, some font-switching or formatting
551 commands may produce an unwanted blank space. This can
552 easily be solved by concatenating the text elements together:
554 @lilypond[quote,verbatim]
558 \concat { 1 \super st }
562 \concat { \dynamic p , }
563 \italic { con dolce espressione }
569 An exhaustive list of font-switching, font-size
570 and font-families related commands can be found in @ref{Font}.
572 Defining custom font sets is also possible, as explained in
580 @funindex \normalsize
590 @c TODO: add @seealso
594 @subsubsection Text alignment
596 @cindex text, aligning
597 @cindex aligning text
599 This subsection discusses how to place text in markup mode,
600 inside a @code{\markup} block. Markup objects can also
601 be moved as a whole, using the syntax described in
602 @rlearning{Moving objects}.
604 @c The padding commands should be mentioned on this page, but
605 @c most of these require \box to be more clearly illustrated. -vv
607 @cindex text, horizontal alignment
608 @cindex horizontal text alignment
609 @funindex \left-align
610 @funindex \center-align
611 @funindex \right-align
613 Markup objects may be aligned in different ways. By default,
614 a text indication is aligned on its left edge: in the following
615 example, there is no difference
616 between the first and the second markup.
618 @lilypond[quote,verbatim,fragment,relative=1]
621 a,-\markup { \left-align poco }
623 a,-\markup { \center-align { poco } }
625 a,-\markup { \right-align poco }
630 The horizontal alignment may be fine-tuned
631 using a numeric value:
633 @lilypond[quote,verbatim,fragment,relative=1]
634 a1-\markup { \halign #-1 poco }
636 a,-\markup { \halign #0 poco }
638 a,-\markup { \halign #0.5 poco }
640 a,-\markup { \halign #2 poco }
644 Some objects may have alignment procedures of their own,
645 and therefore are not affected by these commands. It is
646 possible to move such markup objects as a whole, as shown
647 for instance in @ref{Text marks},
649 @cindex text, vertical alignment
650 @cindex vertical text alignment
654 Vertical alignment is a bit more complex. As stated above,
655 markup objects can be moved as a whole; however, it is also
656 possible to move specific elements inside a markup block.
657 In this case, the element to be moved needs to be preceded
658 with an @emph{anchor point}, that can be another markup element
659 or an invisible object. The following example demonstrates these
660 two possibilities; the last markup in this example has no anchor
661 point, and therefore is not moved.
663 @lilypond[quote,verbatim,fragment,relative=1]
666 \raise #2 { Scène 1 } }
670 \lower #4 \bold { Très modéré } }
673 \raise #4 \italic { Une forêt. } }
677 @funindex \general-align
679 @funindex \translate-scaled
681 Some commands can affect both the horizontal and vertical
682 alignment of text objects in markup mode. Any object
683 affected by these commands must be preceded with an
686 @lilypond[quote,verbatim,fragment,relative=1]
689 \translate #'(-1 . 2) "Scène 1" }
693 \general-align #Y #3.2 \bold "Très modéré" }
697 \translate-scaled #'(-1 . 2) \teeny "Une forêt." }
702 @funindex \center-column
704 @cindex multi-line markup
705 @cindex multi-line text
706 @cindex columns, text
708 A markup object may include several lines of text.
709 In the following example, each element or expression
710 is placed on its own line, either left-aligned or centered:
712 @lilypond[quote,verbatim]
730 @cindex centering text on the page
732 Similarly, a list of elements or expressions may be
733 spread to fill the entire horizontal line width (if there
734 is only one element, it will be centered on the page).
735 These expressions can, in turn, include multi-line text
736 or any other markup expression:
738 @lilypond[quote,verbatim]
741 \line { William S. Gilbert }
743 \huge \smallCaps "The Mikado"
745 \smallCaps "The Town of Titipu"
747 \line { Sir Arthur Sullivan }
758 @cindex wordwrapped text
759 @cindex justified text
761 Long text indications can also be automatically wrapped
762 accordingly to the given line width. These will be
763 either left-aligned or justified, as shown in
764 the following example.
766 @lilypond[quote,verbatim]
769 \line \smallCaps { La vida breve }
770 \line \bold { Acto I }
772 (La escena representa el corral de una casa de
773 gitanos en el AlbaicÃn de Granada. Al fondo una
774 puerta por la que se vé el negro interior de
775 una Fragua, iluminado por los rojos resplandores
780 \line \bold { Acto II }
781 \override #'(line-width . 50)
783 (Calle de Granada. Fachada de la casa de Carmela
784 y su hermano Manuel con grandes ventanas abiertas
785 a través de las que se ve el patio
786 donde se celebra una alegre fiesta)
792 An exhaustive list of text alignment commands
793 can be found in @ref{Align}.
795 @c TODO: add @seealso
797 @node Graphic notation inside markup
798 @subsubsection Graphic notation inside markup
800 @cindex graphics, embedding
801 @cindex drawing graphic objects
803 Various graphic objects may be added to a score,
804 using specific markup commands.
808 @funindex \rounded-box
812 @cindex decorating text
815 Some markup commands allow to decorate text elements
816 with graphics, as demonstrated in the following example.
818 @lilypond[quote,verbatim]
827 \bracket "1866 - 1925"
830 \rounded-box \bold Prelude
835 @funindex \pad-markup
837 @funindex \pad-to-box
838 @funindex \pad-around
840 @cindex padding around text
843 Some commands may require to increase the padding around
844 the text: this is achieved with some specific commands
845 exhaustively described in @ref{Align}.
847 @lilypond[quote,verbatim]
850 \box "Charles Ives (1874 - 1954)"
852 \box \pad-markup #2 "THE UNANSWERED QUESTION"
853 \box \pad-x #8 "A Cosmic Landscape"
860 \box \pad-to-box #'(-5 . 20) #'(0 . 5)
861 \bold "Largo to Presto"
864 "String quartet keeps very even time,
865 Flute quartet keeps very uneven time."
870 @funindex \draw-circle
871 @funindex \filled-box
874 @funindex \arrow-head
876 @cindex graphic notation
877 @cindex symbols, non-musical
879 Other graphic elements or symbols may be printed
880 without requiring any text. As with any markup
881 expression, such objects can be combined together:
883 @lilypond[quote,verbatim]
886 \draw-circle #4 #0.4 ##f
887 \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
894 \arrow-head #Y #DOWN ##f
900 @funindex \postscript
902 @cindex embedded graphics
903 @cindex images, embedding
904 @cindex graphics, embedding
907 Advanced graphic features include the ability to
908 include external image files converted to the
909 Encapsulated PostScript format (@emph{eps}), or
910 to directly embed graphics into the input file,
911 using native PostScript code.
913 @lilypond[quote,verbatim,fragment,relative=1]
916 \epsfile #X #10 #"./context-example.eps"
932 An exhaustive list of graphics-specific commands
933 can be found in @ref{Graphic}.
935 @c TODO: add @seealso (and link with NR Editorial)
937 @node Music notation inside markup
938 @subsubsection Music notation inside markup
940 Various musical notation elements may be added
941 to a score, inside a markup object.
943 Notes and accidentals can be entered using specific
946 @lilypond[quote,verbatim,fragment,relative=2]
950 \note-by-number #1 #1 #1.5
953 \natural \semiflat \flat
954 \sesquiflat \doubleflat
958 \natural \semisharp \sharp
959 \sesquisharp \doublesharp
964 Other notation objects may also be printed
967 @lilypond[quote,verbatim,fragment,relative=1]
974 fis_\markup { \dynamic rf }
985 More generally, any available musical symbol may be
986 included separately in a markup object, using the
989 @lilypond[quote,verbatim,fragment,relative=2]
991 c'^\markup { \musicglyph #"eight" }
993 c,8._\markup { \musicglyph #"clefs.G_change" }
995 c2^\markup { \musicglyph #"timesig.neomensural94" }
997 @c TODO: add \lookup here? -vv
1000 An exhaustive list of these symbols and their names can
1001 be found in @ref {The Feta font}.
1003 The markup mode also supports diagrams for specific
1006 @lilypond[quote,verbatim,fragment,relative=2]
1008 \fret-diagram-terse #"x;x;o;2;3;2;"
1011 \harp-pedal #"^-v|--ov^"
1016 \musicglyph #"accordion.accDiscant"
1018 \raise #0.5 \musicglyph #"accordion.accDot"
1019 \raise #1.5 \musicglyph #"accordion.accDot"
1023 @c The accordion diagram is actually taken from a snippet.
1026 Such diagrams are documented in @ref{Instrument Specific Markup}.
1028 A whole score can even be nested inside a markup object.
1029 In such a case, the nested @code{\score} block must
1030 contain a @code{\layout} block, as demonstrated here:
1032 @lilypond[quote,verbatim,fragment,relative=1]
1035 \relative { c4 d e f }
1043 An exhaustive list of music notation related commands can be
1044 found in @ref{Music}.
1052 @node Multi-page markup
1053 @subsubsection Multi-page markup
1055 Whereas @code{\markup} is used to enter a non-breakable block of
1056 text, @code{\markuplines} can be used at top-level to enter lines
1057 of text that can spread over multiple pages:
1062 A very long text of justified lines.
1066 An other very long paragraph.
1073 @code{\markuplines} accepts a list of markup, that is either the
1074 result of a markup list command, or a list of markups or of markup
1075 lists. The built-in mInstrument Specific Markup arkup list commands are described in
1076 @ref{Text markup list commands}.
1080 This manual: @ref{Text markup list commands}, @ref{New
1081 markup list command definition}.
1088 @funindex \markuplines
1096 * Entire document fonts::
1097 * Single entry fonts::
1100 @node Entire document fonts
1101 @subsubsection Entire document fonts
1103 It is also possible to change the default font family for the
1104 entire document. This is done by calling the
1105 @code{make-pango-font-tree} from within the @code{\paper} block.
1106 The function takes names for the font families to use for roman,
1107 sans serif and monospaced text. For example,
1109 @cindex font families, setting
1118 (make-pango-font-tree "Times New Roman"
1121 (/ myStaffSize 20)))
1125 c'^\markup { roman: foo \sans bla \typewriter bar }
1129 @c we don't do Helvetica / Courier, since GS incorrectly loads
1133 @node Single entry fonts
1134 @subsubsection Single entry fonts
1136 @cindex font selection
1137 @cindex font magnification
1138 @funindex font-interface
1140 By setting the object properties described below, you can select a
1141 font from the preconfigured font families. LilyPond has default
1142 support for the feta music fonts. Text fonts are selected through
1143 Pango/FontConfig. The serif font defaults to New Century
1144 Schoolbook, the sans and typewriter to whatever the Pango
1145 installation defaults to.
1149 @item @code{font-encoding}
1150 is a symbol that sets layout of the glyphs. This should only be
1151 set to select different types of non-text fonts, e.g.
1153 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
1154 standard music font, including ancient glyphs, @code{fetaDynamic}
1155 for dynamic signs and @code{fetaNumber} for the number font.
1157 @item @code{font-family}
1158 is a symbol indicating the general class of the typeface.
1159 Supported are @code{roman} (Computer Modern), @code{sans}, and
1162 @item @code{font-shape}
1163 is a symbol indicating the shape of the font. There are typically
1164 several font shapes available for each font family. Choices are
1165 @code{italic}, @code{caps}, and @code{upright}.
1167 @item @code{font-series}
1168 is a symbol indicating the series of the font. There are
1169 typically several font series for each font family and shape.
1170 Choices are @code{medium} and @code{bold}.
1174 Fonts selected in the way sketched above come from a predefined
1175 style sheet. If you want to use a font from outside the style
1176 sheet, then set the @code{font-name} property,
1178 @lilypond[fragment,verbatim]
1180 \override Staff.TimeSignature #'font-name = #"Charter"
1181 \override Staff.TimeSignature #'font-size = #2
1184 \override #'(font-name . "Vera Bold")
1185 { This text is in Vera Bold }
1191 Any font can be used, as long as it is available to
1192 Pango/FontConfig. To get a full list of all available fonts, run
1196 lilypond -dshow-available-fonts blabla
1199 (the last argument of the command can be anything, but has to be
1203 The size of the font may be set with the @code{font-size}
1204 property. The resulting size is taken relative to the
1205 @code{text-font-size} as defined in the @code{\paper} block.
1208 @cindex font magnification