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 }
98 Snippets: @lsrdir{text}
103 @unnumberedsubsubsec Text scripts
106 @cindex text items, non-empty
107 @cindex non-empty texts
109 It is possible to place arbitrary strings of text or @ref{Text
110 markup}, above or below notes by using a string @code{c^"text"}.
111 By default, these indications do not influence the note spacing,
112 but by using the command @code{\fatText}, the widths will be taken
115 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
116 c4^"longtext" \fatText c4_"longlongtext" c4
120 To prevent text from influencing spacing, use @code{\emptyText}.
122 More complex formatting may also be added to a note by using the
125 @lilypond[fragment,ragged-right,verbatim,quote]
126 c'4^\markup { bla \bold bla }
129 The @code{\markup} is described in more detail in @ref{Text
143 Checking to make sure that text scripts and lyrics are within the
144 margins is a relatively large computational task. To speed up
145 processing, lilypond does not perform such calculations by
146 default; to enable it, use
149 \override Score.PaperColumn #'keep-inside-line = ##t
155 Notation Reference: @ref{Text markup}.
157 Snippets: @lsrdir{text}
159 Internals Reference: @internalsref{TextScript}.
163 @unnumberedsubsubsec Text spanners
165 @cindex Text spanners
167 Some performance indications, e.g., @i{rallentando} or
168 @i{accelerando}, are written as text and are extended over many
169 measures with dotted lines. Such texts are created using text
170 spanners; attach @code{\startTextSpan} and @code{\stopTextSpan} to
171 the first and last notes of the spanner.
173 The string to be printed, as well as the style, is set through
176 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
179 \override TextSpanner #'bound-details #'left #'text =
180 \markup { \upright "rall" }
181 c2\startTextSpan b c\stopTextSpan a
184 \override TextSpanner #'bound-details #'left #'text =
185 \markup { \italic "rit" }
186 c2\startTextSpan b c\stopTextSpan a
191 @funindex textSpannerUp
192 @code{\textSpannerUp},
193 @funindex textSpannerDown
194 @code{\textSpannerDown},
195 @funindex textSpannerNeutral
196 @code{\textSpannerNeutral}.
201 To print a solid line, use
204 \override TextSpanner #'style = #'line
210 Snippets: @lsrdir{text}
212 Internals Reference: @internalsref{TextSpanner}.
216 @unnumberedsubsubsec Text marks
218 @cindex coda on bar line
219 @cindex segno on bar line
220 @cindex fermata on bar line
221 @cindex bar lines, symbols on
224 The @code{\mark} command is primarily used for @ref{Rehearsal
225 marks}, but it can also be used to put signs like coda, segno, and
226 fermata on a bar line. Use @code{\markup} to access the
227 appropriate symbol (symbols are listed in @ref{The Feta font}).
229 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
230 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
235 @code{\mark} is only typeset above the top stave of the score. If
236 you specify the @code{\mark} command at a bar line, the resulting
237 mark is placed above the bar line. If you specify it in the
238 middle of a bar, the resulting mark is positioned between notes.
239 If it is specified before the beginning of a score line, it is
240 placed before the first note of the line. Finally, if the mark
241 occurs at a line break, the mark will be printed at the beginning
244 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
245 @c delete this sentence. -gp
246 If there is no next line, then the mark will not be printed at
252 To print the mark at the end of the current line, use
255 \override Score.RehearsalMark
256 #'break-visibility = #begin-of-line-invisible
259 @code{\mark} is often useful for adding text to the end of bar.
260 In such cases, changing the @code{#'self-alignment} is very useful
262 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
263 \override Score.RehearsalMark
264 #'break-visibility = #begin-of-line-invisible
266 \once \override Score.RehearsalMark #'self-alignment-X = #right
267 \mark "D.S. al Fine "
270 Text marks may be aligned with notation objects other than bar
273 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
278 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
282 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
286 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
295 Possible symbols for the @code{break-align-symbols} list are
296 @code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
297 @code{staff-bar}, @code{left-edge}, @code{key-cancellation},
298 @code{key-signature}, and @code{time-signature}.
300 The text marks will, by default, be aligned with the middle of the
301 notation object, but this can be changed by overriding the
302 @code{break-align-anchor-alignment} and @code{break-align-anchor}
303 properties for the appropriate grob.
305 @lilypond[fragment,quote,ragged-right,verbatim]
307 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
311 % the RehearsalMark will be aligned with the left edge of the KeySignature
312 \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT
317 % the RehearsalMark will be aligned with the right edge of the KeySignature
318 \once \override Staff.KeySignature #'break-align-anchor-alignment = #RIGHT
323 % the RehearsalMark will be aligned with the left edge of the KeySignature
324 % and then shifted right by 2 units.
325 \once \override Staff.KeySignature #'break-align-anchor = #2
331 Although text marks are normally only printed above the topmost
332 staff, you may alter this to print them on every staff,
334 @lilypond[quote,ragged-right,verbatim,relative=2]
337 \remove "Mark_engraver"
341 \consists "Mark_engraver"
343 { c''1 \mark "foo" c'' }
345 \consists "Mark_engraver"
347 { c'1 \mark "foo" c' }
355 Snippets: @lsrdir{text}
357 Internals Reference: @internalsref{RehearsalMark}.
362 @subsection Text markup
365 * Text markup introduction::
367 * Page wrapping text::
371 @node Text markup introduction
372 @unnumberedsubsubsec Text markup introduction
379 Use @code{\markup} to typeset text. Commands are entered with the
380 backslash @code{\}. To enter @code{\} and @code{#}, use double
383 @lilypond[quote,verbatim,fragment,relative=1]
385 c1_\markup { hi there }
386 c1^\markup { hi \bold there, is \italic {anyone home?} }
387 c1_\markup { "\special {weird} #characters" }
391 See @ref{Overview of text markup commands}, for a list of all
394 @code{\markup} is primarily used for @internalsref{TextScript}s,
395 but it can also be used anywhere text is called in lilypond
397 @lilypond[quote,verbatim]
398 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
401 \override Score.RehearsalMark
402 #'break-visibility = #begin-of-line-invisible
403 \override Score.RehearsalMark #'self-alignment-X = #right
405 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
406 c2^\markup{ don't be \flat }
407 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
409 a2\mark \markup{ \large \bold Fine }
413 \addlyrics { bar, foo \markup{ \italic bar! } }
417 A @code{\markup} command can also be placed on its own, away from
418 any @code{\score} block, see @ref{Multiple scores in a book}.
420 @lilypond[quote,ragged-right,verbatim]
421 \markup{ Here is some text. }
424 @cindex font switching
426 The markup in the example demonstrates font switching commands.
427 The command @code{\bold} and @code{\italic} apply to the first
428 following word only; to apply a command to more than one word,
429 enclose the words with braces,
432 \markup @{ \bold @{ hi there @} @}
436 For clarity, you can also do this for single arguments, e.g.,
439 \markup @{ is \italic @{ anyone @} home @}
442 In markup mode you can compose expressions, similar to
443 mathematical expressions, XML documents, and music expressions.
444 You can stack expressions grouped vertically with the command
445 @code{\column}. Similarly, @code{\center-align} aligns texts by
448 @lilypond[quote,verbatim,fragment,relative=1]
449 c1^\markup { \column { a bbbb \line { c d } } }
450 c1^\markup { \center-align { a bbbb c } }
451 c1^\markup { \line { a b c } }
454 Lists with no previous command are not kept distinct. The
458 \center-align @{ @{ a b @} @{ c d @} @}
466 \center-align @{ a b c d @}
471 To keep lists of words distinct, please use quotes @code{"} or
472 the @code{\line} command
474 @lilypond[quote,verbatim,fragment,relative=1]
476 c4^\markup{ \center-align { on three lines } }
477 c4^\markup{ \center-align { "all one line" } }
478 c4^\markup{ \center-align { { on three lines } } }
479 c4^\markup{ \center-align { \line { on one line } } }
482 Markups can be stored in variables and these variables may be
483 attached to notes, like
486 allegro = \markup @{ \bold \large @{ Allegro @} @}
487 @{ a^\allegro b c d @}
490 Some objects have alignment procedures of their own, which cancel
491 out any effects of alignments applied to their markup arguments as
492 a whole. For example, the @internalsref{RehearsalMark} is
493 horizontally centered, so using @code{\mark \markup @{ \left-align
494 .. @}} has no effect.
496 In addition, vertical placement is performed after creating the
497 text markup object. If you wish to move an entire piece of
498 markup, you need to use the #'padding property or create an
499 @q{anchor} point inside the markup (generally with @code{\hspace
502 @lilypond[quote,verbatim,fragment,relative=1]
504 c'4^\markup{ \raise #5 "not raised" }
505 \once \override TextScript #'padding = #3
506 c'4^\markup{ raised }
507 c'4^\markup{ \hspace #0 \raise #1.5 raised }
510 Some situations (such as dynamic marks) have preset font-related
511 properties. If you are creating text in such situations, it is
512 advisable to cancel those properties with @code{normal-text}. See
513 @ref{Overview of text markup commands}, for more details.
518 This manual: @ref{Overview of text markup commands}.
520 Snippets: @lsrdir{text}
522 Internals Reference: @internalsref{TextScript}.
524 Init files: @file{scm/@/new@/-markup@/.scm}.
529 Kerning or generation of ligatures is only done when the @TeX{}
530 backend is used. In this case, LilyPond does not account for them
531 so texts will be spaced slightly too wide.
533 Syntax errors for markup mode are confusing.
537 @unnumberedsubsubsec Nested scores
539 It is possible to nest music inside markups, by adding a
540 @code{\score} block to a markup expression. Such a score must
541 contain a @code{\layout} block.
543 @lilypond[quote,verbatim,ragged-right]
547 \relative { c4 d e f }
557 Snippets: @lsrdir{text}
559 @node Page wrapping text
560 @unnumberedsubsubsec Page wrapping text
562 Whereas @code{\markup} is used to enter a non-breakable block of
563 text, @code{\markuplines} can be used at top-level to enter lines
564 of text that can spread over multiple pages:
569 A very long text of justified lines.
573 An other very long paragraph.
580 @code{\markuplines} accepts a list of markup, that is either the
581 result of a markup list command, or a list of markups or of markup
582 lists. The built-in markup list commands are described in
583 @ref{Overview of text markup list commands}.
587 This manual: @ref{Overview of text markup list commands}, @ref{New
588 markup list command definition}.
590 Snippets: @lsrdir{text}
594 @funindex \markuplines
598 @unnumberedsubsubsec Font selection
600 @cindex font selection
601 @cindex font magnification
602 @funindex font-interface
604 By setting the object properties described below, you can select a
605 font from the preconfigured font families. LilyPond has default
606 support for the feta music fonts. Text fonts are selected through
607 Pango/FontConfig. The serif font defaults to New Century
608 Schoolbook, the sans and typewriter to whatever the Pango
609 installation defaults to.
613 @item @code{font-encoding}
614 is a symbol that sets layout of the glyphs. This should only be
615 set to select different types of non-text fonts, e.g.
617 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
618 standard music font, including ancient glyphs, @code{fetaDynamic}
619 for dynamic signs and @code{fetaNumber} for the number font.
621 @item @code{font-family}
622 is a symbol indicating the general class of the typeface.
623 Supported are @code{roman} (Computer Modern), @code{sans}, and
626 @item @code{font-shape}
627 is a symbol indicating the shape of the font. There are typically
628 several font shapes available for each font family. Choices are
629 @code{italic}, @code{caps}, and @code{upright}.
631 @item @code{font-series}
632 is a symbol indicating the series of the font. There are
633 typically several font series for each font family and shape.
634 Choices are @code{medium} and @code{bold}.
638 Fonts selected in the way sketched above come from a predefined
639 style sheet. If you want to use a font from outside the style
640 sheet, then set the @code{font-name} property,
642 @lilypond[fragment,verbatim]
644 \override Staff.TimeSignature #'font-name = #"Charter"
645 \override Staff.TimeSignature #'font-size = #2
648 \override #'(font-name . "Vera Bold")
649 { This text is in Vera Bold }
655 Any font can be used, as long as it is available to
656 Pango/FontConfig. To get a full list of all available fonts, run
660 lilypond -dshow-available-fonts blabla
663 (the last argument of the command can be anything, but has to be
667 The size of the font may be set with the @code{font-size}
668 property. The resulting size is taken relative to the
669 @code{text-font-size} as defined in the @code{\paper} block.
672 @cindex font magnification
675 It is also possible to change the default font family for the
676 entire document. This is done by calling the
677 @code{make-pango-font-tree} from within the @code{\paper} block.
678 The function takes names for the font families to use for roman,
679 sans serif and monospaced text. For example,
681 @cindex font families, setting
690 (make-pango-font-tree "Times New Roman"
697 c'^\markup { roman: foo \sans bla \typewriter bar }
701 @c we don't do Helvetica / Courier, since GS incorrectly loads
708 Snippets: @lsrdir{text}
711 @node Special text concerns
712 @subsection Special text concerns
717 * New dynamic marks::
718 * Text and line spanners::
721 @node New dynamic marks
722 @unnumberedsubsubsec New dynamic marks
724 It is possible to print new dynamic marks or text that should be
725 aligned with dynamics. Use @code{make-dynamic-script} to create
726 these marks. Note that the dynamic font only contains the
727 characters @code{f,m,p,r,s} and @code{z}.
729 Some situations (such as dynamic marks) have preset font-related
730 properties. If you are creating text in such situations, it is
731 advisable to cancel those properties with @code{normal-text}. See
732 @ref{Overview of text markup commands}, for more details.
734 @cindex make-dynamic-script
736 @lilypond[quote,verbatim,ragged-right]
737 sfzp = #(make-dynamic-script "sfzp")
743 @cindex Dynamics, editorial
744 @cindex Dynamics, parenthesis
746 It is also possible to print dynamics in round parenthesis or
747 square brackets. These are often used for adding editorial
750 @lilypond[quote,verbatim,ragged-right]
751 rndf = \markup{ \center-align {\line { \bold{\italic (}
752 \dynamic f \bold{\italic )} }} }
753 boxf = \markup{ \bracket { \dynamic f } }
754 { c'1_\rndf c'1_\boxf }
759 Snippets: @lsrdir{text}
762 @node Text and line spanners
763 @unnumberedsubsubsec Text and line spanners
765 Some performance indications, e.g., @i{rallentando} and
766 @i{accelerando} and @i{trills} are written as text and are
767 extended over many measures with lines, sometimes dotted or wavy.
769 These all use the same routines as the glissando for drawing the
770 texts and the lines, and tuning their behavior is therefore also
771 done in the same way. It is done with a spanner, and the routine
772 responsible for drawing the spanners is
773 @code{ly:line-interface::print}. This routine determines the
774 exact location of the two @i{span points} and draws a line in
775 between, in the style requested.
777 Here is an example of the different line styles available, and how
780 @lilypond[relative=2,ragged-right,verbatim,fragment]
782 \once \override Glissando #'style = #'dashed-line
784 \override Glissando #'style = #'dotted-line
786 \override Glissando #'style = #'zigzag
788 \override Glissando #'style = #'trill
792 The information that determines the end-points is computed
793 on-the-fly for every graphic object, but it is possible to
796 @lilypond[relative=2,ragged-right,verbatim,fragment]
798 \once \override Glissando #'bound-details #'right #'Y = #-2
802 The @code{Glissando} object, like any other using the
803 @code{ly:line-interface::print} routine, carries a nested
804 association list. In the above statement, the value for @code{Y}
805 is set to @code{-2} for the association list corresponding to the
806 right end point. Of course, it is also possible to adjust the
807 left side with @code{left} instead of @code{right}.
809 If @code{Y} is not set, the value is computed from the vertical
810 position of right attachment point of the spanner.
812 In case of a line break, the values for the span-points are
813 extended with contents of the @code{left-broken} and
814 @code{right-broken} sublists, for example
816 @lilypond[relative=2,ragged-right,verbatim,fragment]
817 \override Glissando #'breakable = ##T
818 \override Glissando #'bound-details #'right-broken #'Y = #-3
823 The following properties can be used for the
827 This sets the Y-coordinate of the end point, in staff space. By
828 default, it is the center of the bound object, so for a glissando
829 it points to the vertical center of the note head.
831 For horizontal spanners, such as text spanner and trill spanners,
832 it is hardcoded to 0.
835 This determines where the line starts and ends in X-direction,
836 relative to the bound object. So, a value of @code{-1} (or
837 @code{LEFT}) makes the line start/end at the left side of the note
838 head it is attached to.
841 This is the absolute coordinate of the end point. It is usually
842 computed on the fly, and there is little use in overriding it.
845 Line spanners may have symbols at the beginning or end, which is
846 contained in this sub-property. This is for internal use, it is
847 recommended to use @code{text}.
850 This is a markup that is evaluated to yield stencil. It is used
851 to put @i{cresc.} and @i{tr} on horizontal spanners.
853 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
854 \override TextSpanner #'bound-details #'left #'text
855 = \markup { \small \bold Slower }
856 c2\startTextSpan b c a\stopTextSpan
859 @item stencil-align-dir-y
861 Without setting this, the stencil is simply put there at the
862 end-point, as defined by the @code{X} and @code{Y} sub properties.
863 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
864 will move the symbol at the edge relative to the end point of the
867 @lilypond[relative=1,fragment,verbatim]
868 \override TextSpanner #'bound-details
869 #'left #'stencil-align-dir-y = #DOWN
870 \override TextSpanner #'bound-details
871 #'right #'stencil-align-dir-y = #UP
873 \override TextSpanner #'bound-details
874 #'left #'text = #"gggg"
875 \override TextSpanner #'bound-details
876 #'right #'text = #"hhhh"
877 c4^\startTextSpan c c c \stopTextSpan
881 Setting this sub property to @code{#t} produce an arrowhead at the
885 This sub property controls the space between the specified
886 end-point of the line and the actual end. Without padding, a
887 glissando would start and end in the center of each note head.
891 TODO: add this somewhere
895 \override TextSpanner #'bound-details #'left-broken #'text = ##f
896 \override TextSpanner #'bound-details #'left #'text = \markup {
898 c'1 \startTextSpan \break
905 The music function \endSpanners terminates spanners and hairpins
906 after exactly one note.
908 @lilypond[verbatim,quote,raged-right,relative=2,fragment]
914 When using \endSpanners it is not necessary to close
915 \startTextSpan with \stopTextSpan, nor is it necessary to close
922 Snippets: @lsrdir{text}
924 Internals Reference: @internalsref{TextSpanner},
925 @internalsref{Glissando}, @internalsref{VoiceFollower},
926 @internalsref{TrillSpanner},
927 @internalsref{line-spanner-interface}.