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.
12 @lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
15 This section explains how to include text (with various
16 formatting) in your scores.
18 @cindex Text, other languages
19 To write accented and special text (such as characters from other
20 languages), simply insert the characters directly into the
21 lilypond file. The file must be saved as UTF-8. For more
22 information, see @ref{Text encoding}.
27 * Special text concerns::
32 @subsection Writing text
35 * Overview of text entry::
41 @node Overview of text entry
42 @subsubsection Overview of text entry
44 There are four ways to add text to scores:
48 @ref{Text scripts}: blah blah
50 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
55 @ref{Text spanners}: blah blah
57 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
59 \override TextSpanner #'bound-details #'left #'text =
60 \markup { \upright "rall" }
61 c2\startTextSpan b c\stopTextSpan a
65 @ref{Text marks}: blah blah
67 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
72 @ref{Vocal music}: blah blah, not in this section.
74 @lilypond[verbatim,quote,ragged-right]
76 \relative c'' { c4 c c c }
77 \addlyrics { one two three four }
85 Snippets: @lsrdir{Text,Text}
90 @subsubsection Text scripts
93 @cindex text items, non-empty
94 @cindex non-empty texts
96 It is possible to place arbitrary strings of text or @ref{Text
97 markup}, above or below notes by using a string @code{c^"text"}.
98 By default, these indications do not influence the note spacing,
99 but by using the command @code{\textLengthOn}, the widths will be taken
102 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
103 c4^"longtext" \textLengthOn c4_"longlongtext" c4
107 To prevent text from influencing spacing, use @code{\textLengthOff}.
109 More complex formatting may also be added to a note by using the
112 @lilypond[fragment,ragged-right,verbatim,quote]
113 c'4^\markup { bla \bold bla }
116 The @code{\markup} is described in more detail in @ref{Text
122 @funindex \textLengthOn
123 @code{\textLengthOn},
124 @funindex \textLengthOff
125 @code{\textLengthOff}.
130 Checking to make sure that text scripts and lyrics are within the
131 margins is a relatively large computational task. To speed up
132 processing, lilypond does not perform such calculations by
133 default; to enable it, use
136 \override Score.PaperColumn #'keep-inside-line = ##t
142 Notation Reference: @ref{Text markup}.
144 Snippets: @lsrdir{Text,Text}
146 Internals Reference: @internalsref{TextScript}.
150 @subsubsection Text spanners
152 @cindex Text spanners
154 Some performance indications, e.g., @i{rallentando} or
155 @i{accelerando}, are written as text and are extended over many
156 measures with dotted lines. Such texts are created using text
157 spanners; attach @code{\startTextSpan} and @code{\stopTextSpan} to
158 the first and last notes of the spanner.
160 The string to be printed, as well as the style, is set through
163 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
166 \override TextSpanner #'bound-details #'left #'text =
167 \markup { \upright "rall" }
168 c2\startTextSpan b c\stopTextSpan a
171 \override TextSpanner #'bound-details #'left #'text =
172 \markup { \italic "rit" }
173 c2\startTextSpan b c\stopTextSpan a
178 @funindex textSpannerUp
179 @code{\textSpannerUp},
180 @funindex textSpannerDown
181 @code{\textSpannerDown},
182 @funindex textSpannerNeutral
183 @code{\textSpannerNeutral}.
188 To print a solid line, use
191 \override TextSpanner #'style = #'line
197 Snippets: @lsrdir{Text,Text}
199 Internals Reference: @internalsref{TextSpanner}.
203 @subsubsection Text marks
205 @cindex coda on bar line
206 @cindex segno on bar line
207 @cindex fermata on bar line
208 @cindex bar lines, symbols on
211 The @code{\mark} command is primarily used for @ref{Rehearsal
212 marks}, but it can also be used to put signs like coda, segno, and
213 fermata on a bar line. Use @code{\markup} to access the
214 appropriate symbol (symbols are listed in @ref{The Feta font}).
216 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
217 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
222 @code{\mark} is only typeset above the top stave of the score. If
223 you specify the @code{\mark} command at a bar line, the resulting
224 mark is placed above the bar line. If you specify it in the
225 middle of a bar, the resulting mark is positioned between notes.
226 If it is specified before the beginning of a score line, it is
227 placed before the first note of the line. Finally, if the mark
228 occurs at a line break, the mark will be printed at the beginning
231 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
232 @c delete this sentence. -gp
233 If there is no next line, then the mark will not be printed at
239 To print the mark at the end of the current line, use
242 \override Score.RehearsalMark
243 #'break-visibility = #begin-of-line-invisible
246 @code{\mark} is often useful for adding text to the end of bar.
247 In such cases, changing the @code{#'self-alignment} is very useful
249 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
250 \override Score.RehearsalMark
251 #'break-visibility = #begin-of-line-invisible
253 \once \override Score.RehearsalMark #'self-alignment-X = #right
254 \mark "D.S. al Fine "
257 Text marks may be aligned with notation objects other than bar
260 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
265 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
269 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
273 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
282 Possible symbols for the @code{break-align-symbols} list are
283 @code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
284 @code{staff-bar}, @code{left-edge}, @code{key-cancellation},
285 @code{key-signature}, and @code{time-signature}.
287 The text marks will, by default, be aligned with the middle of the
288 notation object, but this can be changed by overriding the
289 @code{break-align-anchor-alignment} and @code{break-align-anchor}
290 properties for the appropriate grob. For scores with multiple staves,
291 this setting should be done for all the staves.
293 @lilypond[fragment,quote,ragged-right,verbatim]
295 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
299 % the RehearsalMark will be aligned with the left edge of the KeySignature
300 \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
305 % the RehearsalMark will be aligned with the right edge of the KeySignature
306 \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
311 % the RehearsalMark will be aligned with the left edge of the KeySignature
312 % and then shifted right by 2 units.
313 \once \override Score.KeySignature #'break-align-anchor = #2
319 Although text marks are normally only printed above the topmost
320 staff, you may alter this to print them on every staff,
322 @lilypond[quote,ragged-right,verbatim,relative=2]
325 \remove "Mark_engraver"
329 \consists "Mark_engraver"
331 { c''1 \mark "foo" c'' }
333 \consists "Mark_engraver"
335 { c'1 \mark "foo" c' }
343 Snippets: @lsrdir{Text,Text}
345 Internals Reference: @internalsref{RehearsalMark}.
350 @subsection Text markup
353 * Text markup introduction::
355 * Page wrapping text::
359 @node Text markup introduction
360 @subsubsection Text markup introduction
367 Use @code{\markup} to typeset text. Commands are entered with the
368 backslash @code{\}. To enter @code{\} and @code{#}, use double
371 @lilypond[quote,verbatim,fragment,relative=1]
373 c1_\markup { hi there }
374 c1^\markup { hi \bold there, is \italic {anyone home?} }
375 c1_\markup { "\special {weird} #characters" }
379 See @ref{Overview of text markup commands}, for a list of all
382 @code{\markup} is primarily used for @internalsref{TextScript}s,
383 but it can also be used anywhere text is called in lilypond
385 @lilypond[quote,verbatim]
386 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
389 \override Score.RehearsalMark
390 #'break-visibility = #begin-of-line-invisible
391 \override Score.RehearsalMark #'self-alignment-X = #right
393 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
394 c2^\markup{ don't be \flat }
395 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
397 a2\mark \markup{ \large \bold Fine }
401 \addlyrics { bar, foo \markup{ \italic bar! } }
405 A @code{\markup} command can also be placed on its own, away from
406 any @code{\score} block, see @ref{Multiple scores in a book}.
408 @lilypond[quote,ragged-right,verbatim]
409 \markup{ Here is some text. }
412 @cindex font switching
414 The markup in the example demonstrates font switching commands.
415 The command @code{\bold} and @code{\italic} apply to the first
416 following word only; to apply a command to more than one word,
417 enclose the words with braces,
420 \markup @{ \bold @{ hi there @} @}
424 For clarity, you can also do this for single arguments, e.g.,
427 \markup @{ is \italic @{ anyone @} home @}
430 In markup mode you can compose expressions, similar to
431 mathematical expressions, XML documents, and music expressions.
432 You can stack expressions grouped vertically with the command
433 @code{\column}. Similarly, @code{\center-align} aligns texts by
436 @lilypond[quote,verbatim,fragment,relative=1]
437 c1^\markup { \column { a bbbb \line { c d } } }
438 c1^\markup { \center-align { a bbbb c } }
439 c1^\markup { \line { a b c } }
442 Lists with no previous command are not kept distinct. The
446 \center-align @{ @{ a b @} @{ c d @} @}
454 \center-align @{ a b c d @}
459 To keep lists of words distinct, please use quotes @code{"} or
460 the @code{\line} command
462 @lilypond[quote,verbatim,fragment,relative=1]
464 c4^\markup{ \center-align { on three lines } }
465 c4^\markup{ \center-align { "all one line" } }
466 c4^\markup{ \center-align { { on three lines } } }
467 c4^\markup{ \center-align { \line { on one line } } }
470 Markups can be stored in variables and these variables may be
471 attached to notes, like
474 allegro = \markup @{ \bold \large @{ Allegro @} @}
475 @{ a^\allegro b c d @}
478 Some objects have alignment procedures of their own, which cancel
479 out any effects of alignments applied to their markup arguments as
480 a whole. For example, the @internalsref{RehearsalMark} is
481 horizontally centered, so using @code{\mark \markup @{ \left-align
482 .. @}} has no effect.
484 In addition, vertical placement is performed after creating the
485 text markup object. If you wish to move an entire piece of
486 markup, you need to use the #'padding property or create an
487 @q{anchor} point inside the markup (generally with @code{\hspace
490 @lilypond[quote,verbatim,fragment,relative=1]
492 c'4^\markup{ \raise #5 "not raised" }
493 \once \override TextScript #'padding = #3
494 c'4^\markup{ raised }
495 c'4^\markup{ \hspace #0 \raise #1.5 raised }
498 Some situations (such as dynamic marks) have preset font-related
499 properties. If you are creating text in such situations, it is
500 advisable to cancel those properties with @code{normal-text}. See
501 @ref{Overview of text markup commands}, for more details.
506 This manual: @ref{Overview of text markup commands}.
508 Snippets: @lsrdir{Text,Text}
510 Internals Reference: @internalsref{TextScript}.
512 Init files: @file{scm/@/new@/-markup@/.scm}.
517 Kerning or generation of ligatures is only done when the @TeX{}
518 backend is used. In this case, LilyPond does not account for them
519 so texts will be spaced slightly too wide.
521 Syntax errors for markup mode are confusing.
525 @subsubsection Nested scores
527 It is possible to nest music inside markups, by adding a
528 @code{\score} block to a markup expression. Such a score must
529 contain a @code{\layout} block.
531 @lilypond[quote,verbatim,ragged-right]
535 \relative { c4 d e f }
545 Snippets: @lsrdir{Text,Text}
547 @node Page wrapping text
548 @subsubsection Page wrapping text
550 Whereas @code{\markup} is used to enter a non-breakable block of
551 text, @code{\markuplines} can be used at top-level to enter lines
552 of text that can spread over multiple pages:
557 A very long text of justified lines.
561 An other very long paragraph.
568 @code{\markuplines} accepts a list of markup, that is either the
569 result of a markup list command, or a list of markups or of markup
570 lists. The built-in markup list commands are described in
571 @ref{Overview of text markup list commands}.
575 This manual: @ref{Overview of text markup list commands}, @ref{New
576 markup list command definition}.
578 Snippets: @lsrdir{Text,Text}
582 @funindex \markuplines
586 @subsubsection Font selection
588 @cindex font selection
589 @cindex font magnification
590 @funindex font-interface
592 By setting the object properties described below, you can select a
593 font from the preconfigured font families. LilyPond has default
594 support for the feta music fonts. Text fonts are selected through
595 Pango/FontConfig. The serif font defaults to New Century
596 Schoolbook, the sans and typewriter to whatever the Pango
597 installation defaults to.
601 @item @code{font-encoding}
602 is a symbol that sets layout of the glyphs. This should only be
603 set to select different types of non-text fonts, e.g.
605 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
606 standard music font, including ancient glyphs, @code{fetaDynamic}
607 for dynamic signs and @code{fetaNumber} for the number font.
609 @item @code{font-family}
610 is a symbol indicating the general class of the typeface.
611 Supported are @code{roman} (Computer Modern), @code{sans}, and
614 @item @code{font-shape}
615 is a symbol indicating the shape of the font. There are typically
616 several font shapes available for each font family. Choices are
617 @code{italic}, @code{caps}, and @code{upright}.
619 @item @code{font-series}
620 is a symbol indicating the series of the font. There are
621 typically several font series for each font family and shape.
622 Choices are @code{medium} and @code{bold}.
626 Fonts selected in the way sketched above come from a predefined
627 style sheet. If you want to use a font from outside the style
628 sheet, then set the @code{font-name} property,
630 @lilypond[fragment,verbatim]
632 \override Staff.TimeSignature #'font-name = #"Charter"
633 \override Staff.TimeSignature #'font-size = #2
636 \override #'(font-name . "Vera Bold")
637 { This text is in Vera Bold }
643 Any font can be used, as long as it is available to
644 Pango/FontConfig. To get a full list of all available fonts, run
648 lilypond -dshow-available-fonts blabla
651 (the last argument of the command can be anything, but has to be
655 The size of the font may be set with the @code{font-size}
656 property. The resulting size is taken relative to the
657 @code{text-font-size} as defined in the @code{\paper} block.
660 @cindex font magnification
663 It is also possible to change the default font family for the
664 entire document. This is done by calling the
665 @code{make-pango-font-tree} from within the @code{\paper} block.
666 The function takes names for the font families to use for roman,
667 sans serif and monospaced text. For example,
669 @cindex font families, setting
678 (make-pango-font-tree "Times New Roman"
685 c'^\markup { roman: foo \sans bla \typewriter bar }
689 @c we don't do Helvetica / Courier, since GS incorrectly loads
696 Snippets: @lsrdir{Text,Text}
699 @node Special text concerns
700 @subsection Special text concerns
705 * New dynamic marks::
706 * Text and line spanners::
709 @node New dynamic marks
710 @subsubsection New dynamic marks
712 It is possible to print new dynamic marks or text that should be
713 aligned with dynamics. Use @code{make-dynamic-script} to create
714 these marks. Note that the dynamic font only contains the
715 characters @code{f,m,p,r,s} and @code{z}.
717 Some situations (such as dynamic marks) have preset font-related
718 properties. If you are creating text in such situations, it is
719 advisable to cancel those properties with @code{normal-text}. See
720 @ref{Overview of text markup commands}, for more details.
722 @cindex make-dynamic-script
724 @lilypond[quote,verbatim,ragged-right]
725 sfzp = #(make-dynamic-script "sfzp")
731 @cindex Dynamics, editorial
732 @cindex Dynamics, parenthesis
734 It is also possible to print dynamics in round parenthesis or
735 square brackets. These are often used for adding editorial
738 @lilypond[quote,verbatim,ragged-right]
739 rndf = \markup{ \center-align {\line { \bold{\italic (}
740 \dynamic f \bold{\italic )} }} }
741 boxf = \markup{ \bracket { \dynamic f } }
742 { c'1_\rndf c'1_\boxf }
747 Snippets: @lsrdir{Text,Text}
750 @node Text and line spanners
751 @subsubsection Text and line spanners
753 Some performance indications, e.g., @i{rallentando} and
754 @i{accelerando} and @i{trills} are written as text and are
755 extended over many measures with lines, sometimes dotted or wavy.
757 These all use the same routines as the glissando for drawing the
758 texts and the lines, and tuning their behavior is therefore also
759 done in the same way. It is done with a spanner, and the routine
760 responsible for drawing the spanners is
761 @code{ly:line-interface::print}. This routine determines the
762 exact location of the two @i{span points} and draws a line in
763 between, in the style requested.
765 Here is an example of the different line styles available, and how
768 @lilypond[relative=2,ragged-right,verbatim,fragment]
770 \once \override Glissando #'style = #'dashed-line
772 \override Glissando #'style = #'dotted-line
774 \override Glissando #'style = #'zigzag
776 \override Glissando #'style = #'trill
780 The information that determines the end-points is computed
781 on-the-fly for every graphic object, but it is possible to
784 @lilypond[relative=2,ragged-right,verbatim,fragment]
786 \once \override Glissando #'bound-details #'right #'Y = #-2
790 The @code{Glissando} object, like any other using the
791 @code{ly:line-interface::print} routine, carries a nested
792 association list. In the above statement, the value for @code{Y}
793 is set to @code{-2} for the association list corresponding to the
794 right end point. Of course, it is also possible to adjust the
795 left side with @code{left} instead of @code{right}.
797 If @code{Y} is not set, the value is computed from the vertical
798 position of right attachment point of the spanner.
800 In case of a line break, the values for the span-points are
801 extended with contents of the @code{left-broken} and
802 @code{right-broken} sublists, for example
804 @lilypond[relative=2,ragged-right,verbatim,fragment]
805 \override Glissando #'breakable = ##T
806 \override Glissando #'bound-details #'right-broken #'Y = #-3
811 The following properties can be used for the
815 This sets the Y-coordinate of the end point, in staff space. By
816 default, it is the center of the bound object, so for a glissando
817 it points to the vertical center of the note head.
819 For horizontal spanners, such as text spanner and trill spanners,
820 it is hardcoded to 0.
823 This determines where the line starts and ends in X-direction,
824 relative to the bound object. So, a value of @code{-1} (or
825 @code{LEFT}) makes the line start/end at the left side of the note
826 head it is attached to.
829 This is the absolute coordinate of the end point. It is usually
830 computed on the fly, and there is little use in overriding it.
833 Line spanners may have symbols at the beginning or end, which is
834 contained in this sub-property. This is for internal use, it is
835 recommended to use @code{text}.
838 This is a markup that is evaluated to yield stencil. It is used
839 to put @i{cresc.} and @i{tr} on horizontal spanners.
841 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
842 \override TextSpanner #'bound-details #'left #'text
843 = \markup { \small \bold Slower }
844 c2\startTextSpan b c a\stopTextSpan
847 @item stencil-align-dir-y
849 Without setting this, the stencil is simply put there at the
850 end-point, as defined by the @code{X} and @code{Y} sub properties.
851 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
852 will move the symbol at the edge relative to the end point of the
855 @lilypond[relative=1,fragment,verbatim]
856 \override TextSpanner #'bound-details
857 #'left #'stencil-align-dir-y = #DOWN
858 \override TextSpanner #'bound-details
859 #'right #'stencil-align-dir-y = #UP
861 \override TextSpanner #'bound-details
862 #'left #'text = #"gggg"
863 \override TextSpanner #'bound-details
864 #'right #'text = #"hhhh"
865 c4^\startTextSpan c c c \stopTextSpan
869 Setting this sub property to @code{#t} produce an arrowhead at the
873 This sub property controls the space between the specified
874 end-point of the line and the actual end. Without padding, a
875 glissando would start and end in the center of each note head.
879 TODO: add this somewhere
883 \override TextSpanner #'bound-details #'left-broken #'text = ##f
884 \override TextSpanner #'bound-details #'left #'text = \markup {
886 c'1 \startTextSpan \break
893 The music function \endSpanners terminates spanners and hairpins
894 after exactly one note.
896 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
902 When using \endSpanners it is not necessary to close
903 \startTextSpan with \stopTextSpan, nor is it necessary to close
910 Snippets: @lsrdir{Text,Text}
912 Internals Reference: @internalsref{TextSpanner},
913 @internalsref{Glissando}, @internalsref{VoiceFollower},
914 @internalsref{TrillSpanner},
915 @internalsref{line-spanner-interface}.