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 can 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{@{
350 Unlike simple @q{quoted text} indications, @code{\markup} blocks
351 may contain nested expressions or specific commands,
352 entered using the backslash @code{\} character.
353 Such commands only affect the first following expression.
355 @lilypond[quote,verbatim,fragment,relative=1]
357 a2^\markup { poco \italic più forte }
359 d2_\markup { \italic "string. assai" }
361 b1^\markup { \bold { molto \italic agitato } }
365 @cindex special characters in markup mode
366 @cindex markup mode, special characters
367 @cindex reserved characters, printing
368 @cindex printing special characters
369 @cindex quoted text in markup mode
371 A @code{\markup} block may also contain quoted text, which
372 can be useful to print special characters such as @code{\} and @code{#},
373 or even double quotation marks -- these have to be preceded
376 @lilypond[quote,verbatim,fragment,relative=1]
378 a^\markup "##\ LEPORELLO \##"
379 a_\markup "Bravi! \"Cosa rara\"!"
384 The way markup expressions are defined affects
385 how these expressions will stacked, centered and aligned
386 when using the commands explained in @ref{Text alignment}.
388 @lilypond[quote,verbatim,fragment,relative=1]
389 c1^\markup { \column { a bbbb \line { c d } } }
390 c1^\markup { \center-align { a bbbb c } }
391 c1^\markup { \line { a b c } }
394 Lists of words that are not enclosed with double quotes
395 or preceded by a command are not treated as a distinct
396 expression. In the following example, the first two
397 @code{\markup} expressions are equivalent:
399 @lilypond[quote,verbatim,fragment,relative=1]
400 c1^\markup { \center-align { a bbb c } }
401 c1^\markup { \center-align { a { bbb c } } }
402 c1^\markup { \center-align { a \line { bbb c } } }
406 Markups can be stored in variables. These variables may be
407 directly attached to notes:
409 @lilypond[quote,verbatim]
410 allegro = \markup { \bold \large Allegro }
420 An exhaustive list of @code{\markup}-specific commands can be found in
421 @ref{Text markup commands}.
426 This manual: @ref{Text markup commands}.
431 Internals Reference: @rinternals{TextScript}.
433 Init files: @file{scm/@/new@/-markup@/.scm}.
438 Syntax errors for markup mode can be confusing.
441 @node Selecting font and font size
442 @subsubsection Selecting font and font size
444 @cindex font switching
449 Basic font switching is supported in markup mode:
451 @lilypond[quote,verbatim,relative=2]
455 \italic { non troppo \underline Vivo }
458 d,_\markup { \italic quasi \smallCaps Tromba }
471 The size of the characters can also be altered in different ways:
474 the font size can be defined to an absolute value,
477 predefined commands allow to easily select standard sizes,
480 the font size can also be changed relatively to its previous value.
484 The following example demonstrates these three methods:
486 @lilypond[quote,verbatim,relative=2]
488 f1^\markup { \fontsize #5 Sinfonia }
497 \magnify #0.6 { e sentimento } )
508 Text may be printed as subscript or superscript. By default
509 these are printed in a smaller size, but a normal size can be used as well:
511 @lilypond[quote,verbatim]
514 \line { 1 \super st movement }
515 \line { 1 \normal-size-super st movement
516 \sub { (part two) } }
521 @cindex font families
523 The markup mode provides an easy way to select alternate
524 font families. The default serif font, of roman type, is automatically
525 selected unless specified otherwise: on the last line of the following example,
526 there is no difference between the first word and the second word.
528 @lilypond[quote,verbatim]
531 \line { Act \number 1 }
532 \line { \sans { Scene I. } }
533 \line { \typewriter { Verona. An open place. } }
534 \line { Enter \roman Valentine and Proteus. }
540 Some of these font families, used for specific items
541 such as numbers or dynamics, do not provide all
542 characters, as mentioned in @ref{New dynamic marks} and
543 @ref{Manual repeat marks}.
546 Defining custom font sets is also possible, as explained in
547 @ref{Fonts}. An exhaustive list of font-switching, font-size
548 and font-families related commands can be found in @ref{Font}.
555 @funindex \normalsize
566 @c TODO: add @seealso
569 When used inside a word, some of these commands may produce an unwanted
570 blank space. This can easily be solved by concatenating the text
571 elements together, using a specific command
572 described in @ref{Text alignment}.
577 @subsubsection Text alignment
579 @cindex text, aligning
580 @cindex aligning text
582 This subsection discusses how to place text in markup mode,
583 inside a @code{\markup} block. Markup objects can also
584 be moved as a whole, using the syntax described in
585 @rlearning{Moving objects}.
587 @cindex text, horizontal alignment
588 @cindex horizontal text alignment
589 @funindex \left-align
591 @funindex \right-align
593 Markup objects may be aligned in different ways. By default,
594 a text indication is aligned on its left edge: in the following
595 example, there's no difference between the first and the second
598 @lilypond[quote,verbatim,fragment,relative=1]
601 a,-\markup { \left-align poco }
603 a,-\markup { \hcenter { poco } }
605 a,-\markup { \right-align poco }
610 The horizontal alignment may be fine-tuned
611 using a numeric value:
613 @lilypond[quote,verbatim,fragment,relative=1]
614 a1-\markup { \halign #-1 poco }
616 a,-\markup { \halign #0 poco }
618 a,-\markup { \halign #0.5 poco }
620 a,-\markup { \halign #2 poco }
623 @cindex text, vertical alignment
624 @cindex vertical text alignment
628 Vertical alignment is a bit more complex. As stated above,
629 markup objects can be moved as a whole; however, it is also
630 possible to move specific elements inside a markup block.
631 In this case, the element to be moved needs to be preceded
632 with an @emph{anchor point}, that can be another markup element
633 or an invisible object. The following example demonstrates these
634 two possibilities; the last markup in this example has no anchor
635 point, and therefore is not moved.
637 @lilypond[quote,verbatim,fragment,relative=1]
640 \raise #2 { Scène 1 } }
644 \lower #4 \bold { Très modéré } }
647 \raise #4 \italic { Une forêt. } }
651 @funindex \general-align
653 @funindex \translate-scaled
655 Some commands can affect both the horizontal and vertical
656 alignment of text objects in markup mode. Any object
657 affected by these commands must be preceded by an
660 @lilypond[quote,verbatim,fragment,relative=1]
663 \translate #'(-1 . 2) "Scène 1" }
667 \general-align #Y #3.2 \bold "Très modéré" }
671 \translate-scaled #'(-1 . 2) \teeny "Une forêt." }
675 @cindex multi-line markup
676 @cindex multi-line text
677 @cindex columns, text
679 A markup object may include several lines of text.
680 In the following example, each element or expression
681 is placed on its own line:
683 @lilypond[quote,verbatim]
698 Building a "large" markup:
711 Alignment inside a "large" markup:
723 TODO: here are some commands that could be described here.
724 I'm putting them in bulk, prior to working on this section. -vv
736 \page-ref (see also "Table of contents")
749 Some objects have alignment procedures of their own, which cancel
750 out any effects of alignments applied to their markup arguments as
751 a whole. For example, the @rinternals{RehearsalMark} is
752 horizontally centered, so using @code{\mark \markup @{ \left-align
753 .. @}} has no effect.
757 @node Graphic notation inside markup
758 @subsubsection Graphic notation inside markup
759 Graphics around text:
766 "Standalone" graphics:
786 @node Music notation inside markup
787 @subsubsection Music notation inside markup
789 Notes can be printed in markup mode blah blah:
794 Accidental symbols can be obtained easily:
806 Some other notation objects blah blah
814 @c TODO: add \text here? -vv
816 Any musical symbol can be printed
819 @c TODO: add \lookup here? -vv
822 The markup mode has support for fret diagrams:
826 \fret-diagram-verbose
828 An entire @code{\score} block can even be nested in a @code{\markup}
829 block. In such a case, the @code{\score} must contain a @code{\layout} block.
835 @lilypond[quote,verbatim,ragged-right]
839 \relative { c4 d e f }
852 @node Multi-page markup
853 @subsubsection Multi-page markup
855 Whereas @code{\markup} is used to enter a non-breakable block of
856 text, @code{\markuplines} can be used at top-level to enter lines
857 of text that can spread over multiple pages:
862 A very long text of justified lines.
866 An other very long paragraph.
873 @code{\markuplines} accepts a list of markup, that is either the
874 result of a markup list command, or a list of markups or of markup
875 lists. The built-in markup list commands are described in
876 @ref{Text markup list commands}.
880 This manual: @ref{Text markup list commands}, @ref{New
881 markup list command definition}.
888 @funindex \markuplines
896 * Entire document fonts::
897 * Single entry fonts::
900 @node Entire document fonts
901 @subsubsection Entire document fonts
903 It is also possible to change the default font family for the
904 entire document. This is done by calling the
905 @code{make-pango-font-tree} from within the @code{\paper} block.
906 The function takes names for the font families to use for roman,
907 sans serif and monospaced text. For example,
909 @cindex font families, setting
918 (make-pango-font-tree "Times New Roman"
925 c'^\markup { roman: foo \sans bla \typewriter bar }
929 @c we don't do Helvetica / Courier, since GS incorrectly loads
933 @node Single entry fonts
934 @subsubsection Single entry fonts
936 @cindex font selection
937 @cindex font magnification
938 @funindex font-interface
940 By setting the object properties described below, you can select a
941 font from the preconfigured font families. LilyPond has default
942 support for the feta music fonts. Text fonts are selected through
943 Pango/FontConfig. The serif font defaults to New Century
944 Schoolbook, the sans and typewriter to whatever the Pango
945 installation defaults to.
949 @item @code{font-encoding}
950 is a symbol that sets layout of the glyphs. This should only be
951 set to select different types of non-text fonts, e.g.
953 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
954 standard music font, including ancient glyphs, @code{fetaDynamic}
955 for dynamic signs and @code{fetaNumber} for the number font.
957 @item @code{font-family}
958 is a symbol indicating the general class of the typeface.
959 Supported are @code{roman} (Computer Modern), @code{sans}, and
962 @item @code{font-shape}
963 is a symbol indicating the shape of the font. There are typically
964 several font shapes available for each font family. Choices are
965 @code{italic}, @code{caps}, and @code{upright}.
967 @item @code{font-series}
968 is a symbol indicating the series of the font. There are
969 typically several font series for each font family and shape.
970 Choices are @code{medium} and @code{bold}.
974 Fonts selected in the way sketched above come from a predefined
975 style sheet. If you want to use a font from outside the style
976 sheet, then set the @code{font-name} property,
978 @lilypond[fragment,verbatim]
980 \override Staff.TimeSignature #'font-name = #"Charter"
981 \override Staff.TimeSignature #'font-size = #2
984 \override #'(font-name . "Vera Bold")
985 { This text is in Vera Bold }
991 Any font can be used, as long as it is available to
992 Pango/FontConfig. To get a full list of all available fonts, run
996 lilypond -dshow-available-fonts blabla
999 (the last argument of the command can be anything, but has to be
1003 The size of the font may be set with the @code{font-size}
1004 property. The resulting size is taken relative to the
1005 @code{text-font-size} as defined in the @code{\paper} block.
1008 @cindex font magnification