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 This section explains how to include text (with various
13 formatting) in your scores.
15 @cindex Text, other languages
16 To write accented and special text (such as characters from other
17 languages), simply insert the characters directly into the
18 lilypond file. The file must be saved as UTF-8. For more
19 information, see @ref{Text encoding}.
21 @lilypond[fragment,ragged-right,staffsize=16,quote]
22 c'4^\markup { bla \bold bla }
25 @lilypond[fragment,ragged-right,staffsize=16,quote]
26 c'4^\markup { bla \bold bla }
29 @lilypond[fragment,ragged-right,staffsize=16,quote]
30 c'4^\markup { bla \bold bla }
33 @lilypond[fragment,ragged-right,staffsize=16,quote]
34 c'4^\markup { bla \bold bla }
40 * Special text concerns::
45 @subsection Writing text
48 * Overview of text entry::
54 @node Overview of text entry
55 @unnumberedsubsubsec Overview of text entry
57 There are four ways to add text to scores:
61 @ref{Text scripts}: blah blah
63 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
68 @ref{Text spanners}: blah blah
70 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
72 \override TextSpanner #'bound-details #'left #'text =
73 \markup { \upright "rall" }
74 c2\startTextSpan b c\stopTextSpan a
78 @ref{Text marks}: blah blah
80 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
85 @ref{Vocal music}: blah blah, not in this section.
87 @lilypond[verbatim,quote,ragged-right]
89 \relative c'' { c4 c c c }
90 \addlyrics { one two three four }
99 @unnumberedsubsubsec Text scripts
102 @cindex text items, non-empty
103 @cindex non-empty texts
105 It is possible to place arbitrary strings of text or @ref{Text
106 markup}, above or below notes by using a string @code{c^"text"}.
107 By default, these indications do not influence the note spacing,
108 but by using the command @code{\fatText}, the widths will be taken
111 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
112 c4^"longtext" \fatText c4_"longlongtext" c4
116 To prevent text from influencing spacing, use @code{\emptyText}.
118 More complex formatting may also be added to a note by using the
121 @lilypond[fragment,ragged-right,verbatim,quote]
122 c'4^\markup { bla \bold bla }
125 The @code{\markup} is described in more detail in @ref{Text
139 Checking to make sure that text scripts and lyrics are within the
140 margins is a relatively large computational task. To speed up
141 processing, lilypond does not perform such calculations by
142 default; to enable it, use
145 \override Score.PaperColumn #'keep-inside-line = ##t
151 Notation Reference: @ref{Text markup}.
153 Internals Reference: @internalsref{TextScript}.
157 @unnumberedsubsubsec Text spanners
159 @cindex Text spanners
161 Some performance indications, e.g., @i{rallentando} or
162 @i{accelerando}, are written as text and are extended over many
163 measures with dotted lines. Such texts are created using text
164 spanners; attach @code{\startTextSpan} and @code{\stopTextSpan} to
165 the first and last notes of the spanner.
167 The string to be printed, as well as the style, is set through
170 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
173 \override TextSpanner #'bound-details #'left #'text =
174 \markup { \upright "rall" }
175 c2\startTextSpan b c\stopTextSpan a
178 \override TextSpanner #'bound-details #'left #'text =
179 \markup { \italic "rit" }
180 c2\startTextSpan b c\stopTextSpan a
185 @funindex textSpannerUp
186 @code{\textSpannerUp},
187 @funindex textSpannerDown
188 @code{\textSpannerDown},
189 @funindex textSpannerNeutral
190 @code{\textSpannerNeutral}.
195 To print a solid line, use
198 \override TextSpanner #'style = #'line
204 Internals Reference: @internalsref{TextSpanner}.
208 @unnumberedsubsubsec Text marks
210 @cindex coda on bar line
211 @cindex segno on bar line
212 @cindex fermata on bar line
213 @cindex bar lines, symbols on
216 The @code{\mark} command is primarily used for @ref{Rehearsal
217 marks}, but it can also be used to put signs like coda, segno, and
218 fermata on a bar line. Use @code{\markup} to access the
219 appropriate symbol (symbols are listed in @ref{The Feta font}).
221 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
222 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
227 @code{\mark} is only typeset above the top stave of the score. If
228 you specify the @code{\mark} command at a bar line, the resulting
229 mark is placed above the bar line. If you specify it in the
230 middle of a bar, the resulting mark is positioned between notes.
231 If it is specified before the beginning of a score line, it is
232 placed before the first note of the line. Finally, if the mark
233 occurs at a line break, the mark will be printed at the beginning
236 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
237 @c delete this sentence. -gp
238 If there is no next line, then the mark will not be printed at
244 To print the mark at the end of the current line, use
247 \override Score.RehearsalMark
248 #'break-visibility = #begin-of-line-invisible
251 @code{\mark} is often useful for adding text to the end of bar.
252 In such cases, changing the @code{#'self-alignment} is very useful
254 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
255 \override Score.RehearsalMark
256 #'break-visibility = #begin-of-line-invisible
258 \once \override Score.RehearsalMark #'self-alignment-X = #right
259 \mark "D.S. al Fine "
262 Text marks may be aligned with notation objects other than bar
265 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
270 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
274 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
278 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
287 Possible symbols for the @code{break-align-symbols} list are
288 @code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
289 @code{staff-bar}, @code{left-edge}, @code{key-cancellation},
290 @code{key-signature}, and @code{time-signature}.
292 The text marks will, by default, be aligned with the middle of the
293 notation object, but this can be changed by overriding the
294 @code{break-align-anchor-alignment} and @code{break-align-anchor}
295 properties for the appropriate grob.
297 @lilypond[fragment,quote,ragged-right,verbatim]
299 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
303 % the RehearsalMark will be aligned with the left edge of the KeySignature
304 \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT
309 % the RehearsalMark will be aligned with the right edge of the KeySignature
310 \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT
315 % the RehearsalMark will be aligned with the left edge of the KeySignature
316 % and then shifted right by 2 units.
317 \once \override Staff.KeySignature #'break-align-anchor = #2
323 Although text marks are normally only printed above the topmost
324 staff, you may alter this to print them on every staff,
326 @lilypond[quote,ragged-right,verbatim,relative=2]
329 \remove "Mark_engraver"
333 \consists "Mark_engraver"
335 { c''1 \mark "foo" c'' }
337 \consists "Mark_engraver"
339 { c'1 \mark "foo" c' }
347 Internals Reference: @internalsref{RehearsalMark}.
352 @subsection Text markup
355 * Text markup introduction::
357 * Page wrapping text::
361 @node Text markup introduction
362 @unnumberedsubsubsec Text markup introduction
369 Use @code{\markup} to typeset text. Commands are entered with the
370 backslash @code{\}. To enter @code{\} and @code{#}, use double
373 @lilypond[quote,verbatim,fragment,relative=1]
375 c1_\markup { hi there }
376 c1^\markup { hi \bold there, is \italic {anyone home?} }
377 c1_\markup { "\special {weird} #characters" }
381 See @ref{Overview of text markup commands}, for a list of all
384 @code{\markup} is primarily used for @internalsref{TextScript}s,
385 but it can also be used anywhere text is called in lilypond
387 @lilypond[quote,verbatim]
388 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
391 \override Score.RehearsalMark
392 #'break-visibility = #begin-of-line-invisible
393 \override Score.RehearsalMark #'self-alignment-X = #right
395 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
396 c2^\markup{ don't be \flat }
397 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
399 a2\mark \markup{ \large \bold Fine }
403 \addlyrics { bar, foo \markup{ \italic bar! } }
407 A @code{\markup} command can also be placed on its own, away from
408 any @code{\score} block, see @ref{Multiple scores in a book}.
410 @lilypond[quote,ragged-right,verbatim]
411 \markup{ Here is some text. }
414 @cindex font switching
416 The markup in the example demonstrates font switching commands.
417 The command @code{\bold} and @code{\italic} apply to the first
418 following word only; to apply a command to more than one word,
419 enclose the words with braces,
422 \markup @{ \bold @{ hi there @} @}
426 For clarity, you can also do this for single arguments, e.g.,
429 \markup @{ is \italic @{ anyone @} home @}
432 In markup mode you can compose expressions, similar to
433 mathematical expressions, XML documents, and music expressions.
434 You can stack expressions grouped vertically with the command
435 @code{\column}. Similarly, @code{\center-align} aligns texts by
438 @lilypond[quote,verbatim,fragment,relative=1]
439 c1^\markup { \column { a bbbb \line { c d } } }
440 c1^\markup { \center-align { a bbbb c } }
441 c1^\markup { \line { a b c } }
444 Lists with no previous command are not kept distinct. The
448 \center-align @{ @{ a b @} @{ c d @} @}
456 \center-align @{ a b c d @}
461 To keep lists of words distinct, please use quotes @code{"} or
462 the @code{\line} command
464 @lilypond[quote,verbatim,fragment,relative=1]
466 c4^\markup{ \center-align { on three lines } }
467 c4^\markup{ \center-align { "all one line" } }
468 c4^\markup{ \center-align { { on three lines } } }
469 c4^\markup{ \center-align { \line { on one line } } }
472 Markups can be stored in variables and these variables may be
473 attached to notes, like
476 allegro = \markup @{ \bold \large @{ Allegro @} @}
477 @{ a^\allegro b c d @}
480 Some objects have alignment procedures of their own, which cancel
481 out any effects of alignments applied to their markup arguments as
482 a whole. For example, the @internalsref{RehearsalMark} is
483 horizontally centered, so using @code{\mark \markup @{ \left-align
484 .. @}} has no effect.
486 In addition, vertical placement is performed after creating the
487 text markup object. If you wish to move an entire piece of
488 markup, you need to use the #'padding property or create an
489 @q{anchor} point inside the markup (generally with @code{\hspace
492 @lilypond[quote,verbatim,fragment,relative=1]
494 c'4^\markup{ \raise #5 "not raised" }
495 \once \override TextScript #'padding = #3
496 c'4^\markup{ raised }
497 c'4^\markup{ \hspace #0 \raise #1.5 raised }
500 Some situations (such as dynamic marks) have preset font-related
501 properties. If you are creating text in such situations, it is
502 advisable to cancel those properties with @code{normal-text}. See
503 @ref{Overview of text markup commands}, for more details.
508 This manual: @ref{Overview of text markup commands}.
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 @unnumberedsubsubsec 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 }
543 @node Page wrapping text
544 @unnumberedsubsubsec Page wrapping text
546 Whereas @code{\markup} is used to enter a non-breakable block of
547 text, @code{\markuplines} can be used at top-level to enter lines
548 of text that can spread over multiple pages:
553 A very long text of justified lines.
557 An other very long paragraph.
564 @code{\markuplines} accepts a list of markup, that is either the
565 result of a markup list command, or a list of markups or of markup
566 lists. The built-in markup list commands are described in
567 @ref{Overview of text markup list commands}.
571 This manual: @ref{Overview of text markup list commands}, @ref{New
572 markup list command definition}.
576 @funindex \markuplines
580 @unnumberedsubsubsec Font selection
582 @cindex font selection
583 @cindex font magnification
584 @funindex font-interface
586 By setting the object properties described below, you can select a
587 font from the preconfigured font families. LilyPond has default
588 support for the feta music fonts. Text fonts are selected through
589 Pango/FontConfig. The serif font defaults to New Century
590 Schoolbook, the sans and typewriter to whatever the Pango
591 installation defaults to.
595 @item @code{font-encoding}
596 is a symbol that sets layout of the glyphs. This should only be
597 set to select different types of non-text fonts, e.g.
599 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
600 standard music font, including ancient glyphs, @code{fetaDynamic}
601 for dynamic signs and @code{fetaNumber} for the number font.
603 @item @code{font-family}
604 is a symbol indicating the general class of the typeface.
605 Supported are @code{roman} (Computer Modern), @code{sans}, and
608 @item @code{font-shape}
609 is a symbol indicating the shape of the font. There are typically
610 several font shapes available for each font family. Choices are
611 @code{italic}, @code{caps}, and @code{upright}.
613 @item @code{font-series}
614 is a symbol indicating the series of the font. There are
615 typically several font series for each font family and shape.
616 Choices are @code{medium} and @code{bold}.
620 Fonts selected in the way sketched above come from a predefined
621 style sheet. If you want to use a font from outside the style
622 sheet, then set the @code{font-name} property,
624 @lilypond[fragment,verbatim]
626 \override Staff.TimeSignature #'font-name = #"Charter"
627 \override Staff.TimeSignature #'font-size = #2
630 \override #'(font-name . "Vera Bold")
631 { This text is in Vera Bold }
637 Any font can be used, as long as it is available to
638 Pango/FontConfig. To get a full list of all available fonts, run
642 lilypond -dshow-available-fonts blabla
645 (the last argument of the command can be anything, but has to be
649 The size of the font may be set with the @code{font-size}
650 property. The resulting size is taken relative to the
651 @code{text-font-size} as defined in the @code{\paper} block.
654 @cindex font magnification
657 It is also possible to change the default font family for the
658 entire document. This is done by calling the
659 @code{make-pango-font-tree} from within the @code{\paper} block.
660 The function takes names for the font families to use for roman,
661 sans serif and monospaced text. For example,
663 @cindex font families, setting
672 (make-pango-font-tree "Times New Roman"
679 c'^\markup { roman: foo \sans bla \typewriter bar }
683 @c we don't do Helvetica / Courier, since GS incorrectly loads
690 Examples: @lsr{text,font@/-family@/-override.ly}.
693 @node Special text concerns
694 @subsection Special text concerns
699 * New dynamic marks::
700 * Text and line spanners::
703 @node New dynamic marks
704 @unnumberedsubsubsec New dynamic marks
706 It is possible to print new dynamic marks or text that should be
707 aligned with dynamics. Use @code{make-dynamic-script} to create
708 these marks. Note that the dynamic font only contains the
709 characters @code{f,m,p,r,s} and @code{z}.
711 Some situations (such as dynamic marks) have preset font-related
712 properties. If you are creating text in such situations, it is
713 advisable to cancel those properties with @code{normal-text}. See
714 @ref{Overview of text markup commands}, for more details.
716 @cindex make-dynamic-script
718 @lilypond[quote,verbatim,ragged-right]
719 sfzp = #(make-dynamic-script "sfzp")
725 @cindex Dynamics, editorial
726 @cindex Dynamics, parenthesis
728 It is also possible to print dynamics in round parenthesis or
729 square brackets. These are often used for adding editorial
732 @lilypond[quote,verbatim,ragged-right]
733 rndf = \markup{ \center-align {\line { \bold{\italic (}
734 \dynamic f \bold{\italic )} }} }
735 boxf = \markup{ \bracket { \dynamic f } }
736 { c'1_\rndf c'1_\boxf }
740 @node Text and line spanners
741 @unnumberedsubsubsec Text and line spanners
743 Some performance indications, e.g., @i{rallentando} and
744 @i{accelerando} and @i{trills} are written as text and are
745 extended over many measures with lines, sometimes dotted or wavy.
747 These all use the same routines as the glissando for drawing the
748 texts and the lines, and tuning their behavior is therefore also
749 done in the same way. It is done with a spanner, and the routine
750 responsible for drawing the spanners is
751 @code{ly:line-interface::print}. This routine determines the
752 exact location of the two @i{span points} and draws a line in
753 between, in the style requested.
755 Here is an example of the different line styles available, and how
758 @lilypond[relative=2,ragged-right,verbatim,fragment]
760 \once \override Glissando #'dash-fraction = #0.5
762 \override Glissando #'style = #'dotted-line
764 \override Glissando #'style = #'zigzag
766 \override Glissando #'style = #'trill
770 The information that determines the end-points is computed
771 on-the-fly for every graphic object, but it is possible to
774 @lilypond[relative=2,ragged-right,verbatim,fragment]
776 \once \override Glissando #'bound-details #'right #'Y = #-2
780 The @code{Glissando} object, like any other using the
781 @code{ly:line-interface::print} routine, carries a nested
782 association list. In the above statement, the value for @code{Y}
783 is set to @code{-2} for the association list corresponding to the
784 right end point. Of course, it is also possible to adjust the
785 left side with @code{left} instead of @code{right}.
787 If @code{Y} is not set, the value is computed from the vertical
788 position of right attachment point of the spanner.
790 In case of a line break, the values for the span-points are
791 extended with contents of the @code{left-broken} and
792 @code{right-broken} sublists, for example
794 @lilypond[relative=2,ragged-right,verbatim,fragment]
795 \override Glissando #'breakable = ##T
796 \override Glissando #'bound-details #'right-broken #'Y = #-3
801 The following properties can be used for the
805 This sets the Y-coordinate of the end point, in staff space. By
806 default, it is the center of the bound object, so for a glissando
807 it points to the vertical center of the note head.
809 For horizontal spanners, such as text spanner and trill spanners,
810 it is hardcoded to 0.
813 This determines where the line starts and ends in X-direction,
814 relative to the bound object. So, a value of @code{-1} (or
815 @code{LEFT}) makes the line start/end at the left side of the note
816 head it is attached to.
819 This is the absolute coordinate of the end point. It is usually
820 computed on the fly, and there is little use in overriding it.
823 Line spanners may have symbols at the beginning or end, which is
824 contained in this sub-property. This is for internal use, it is
825 recommended to use @code{text}.
828 This is a markup that is evaluated to yield stencil. It is used
829 to put @i{cresc.} and @i{tr} on horizontal spanners.
831 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
832 \override TextSpanner #'bound-details #'left #'text
833 = \markup { \small \bold Slower }
834 c2\startTextSpan b c a\stopTextSpan
837 @item stencil-align-dir-y
839 Without setting this, the stencil is simply put there at the
840 end-point, as defined by the @code{X} and @code{Y} sub properties.
841 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
842 will move the symbol at the edge relative to the end point of the
845 @lilypond[relative=1,fragment,verbatim]
846 \override TextSpanner #'bound-details
847 #'left #'stencil-align-dir-y = #DOWN
848 \override TextSpanner #'bound-details
849 #'right #'stencil-align-dir-y = #UP
851 \override TextSpanner #'bound-details
852 #'left #'text = #"gggg"
853 \override TextSpanner #'bound-details
854 #'right #'text = #"hhhh"
855 c4^\startTextSpan c c c \stopTextSpan
859 Setting this sub property to @code{#t} produce an arrowhead at the
863 This sub property controls the space between the specified
864 end-point of the line and the actual end. Without padding, a
865 glissando would start and end in the center of each note head.
869 TODO: add this somewhere
873 \override TextSpanner #'bound-details #'left-broken #'text = ##f
874 \override TextSpanner #'bound-details #'left #'text = \markup {
876 c'1 \startTextSpan \break
883 The music function \endSpanners terminates spanners and hairpins
884 after exactly one note.
886 @lilypond[verbatim,quote,raged-right,relative=2,fragment]
892 When using \endSpanners it is not necessary to close
893 \startTextSpan with \stopTextSpan, nor is it necessary to close
900 Internals Reference: @internalsref{TextSpanner},
901 @internalsref{Glissando}, @internalsref{VoiceFollower},
902 @internalsref{TrillSpanner},
903 @internalsref{line-spanner-interface}.
905 Examples: @lsr{expressive,line-styles.ly},
906 @lsr{expressive,line-arrows.ly}