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 @warning{To write accented and special text (such as characters
20 from other languages), simply insert the characters directly into
21 the 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} with @var{note}@code{-"}@var{text}@code{"}.
101 More complex formatting may also be added to a note by using the
102 @code{\markup} command, as described in @ref{Text markup}.
104 @lilypond[fragment,ragged-right,verbatim,quote]
105 c'4^\markup { bla \bold bla }
110 @funindex \textLengthOn
111 @code{\textLengthOn},
112 @funindex \textLengthOff
113 @code{\textLengthOff}.
117 @c TODO: put this in the LSR. -vv
118 By default, these indications do not influence the note spacing.
119 However, by using the command @code{\textLengthOn}, the widths
120 will be taken into account:
122 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
123 c4^"this does not affect spacing" \textLengthOn c4_"whereas this does" c4
127 After having used such a command, to go back to the default behavior
128 and prevent text from influencing spacing, use @code{\textLengthOff}.
131 @c TODO: LSR-ize this as well -vv
132 Checking to make sure that text scripts and lyrics are within the
133 margins is a relatively large computational task. To speed up
134 processing, lilypond does not perform such calculations by
135 default; to enable it, use
138 \override Score.PaperColumn #'keep-inside-line = ##t
144 Notation Reference: @ref{Text markup}.
146 Snippets: @lsrdir{Text,Text}
148 Internals Reference: @internalsref{TextScript}.
152 @subsubsection Text spanners
154 @cindex Text spanners
156 @c TODO: merge these explanations with the ones below in
157 @c "Text and Line spanners" -vv
159 Some performance indications, e.g., @i{rallentando} or
160 @i{accelerando}, are written as text and are extended over many
161 measures with dotted lines. Such texts are created using text
162 spanners; attach @code{\startTextSpan} and @code{\stopTextSpan} to
163 the first and last notes of the spanner.
165 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
167 \override TextSpanner #'bound-details #'left #'text = "faster"
168 c2\startTextSpan b c\stopTextSpan a
172 The string to be printed, as well as the style, is set through
173 object properties. It can accept @code{\markup} blocks as well:
175 @lilypond[quote,ragged-right,fragment,relative=1,verbatim]
178 \override TextSpanner #'bound-details #'left #'text =
179 \markup { \upright "rall" }
180 c2\startTextSpan b c\stopTextSpan a
183 \override TextSpanner #'bound-details #'left #'text =
184 \markup { \italic "rit" }
185 c2\startTextSpan b c\stopTextSpan a
190 @funindex textSpannerUp
191 @code{\textSpannerUp},
192 @funindex textSpannerDown
193 @code{\textSpannerDown},
194 @funindex textSpannerNeutral
195 @code{\textSpannerNeutral}.
200 To print a solid line, use
203 \override TextSpanner #'style = #'line
209 Snippets: @lsrdir{Text,Text}
211 Internals Reference: @internalsref{TextSpanner}.
215 @subsubsection Text marks
217 @cindex coda on bar line
218 @cindex segno on bar line
219 @cindex fermata on bar line
220 @cindex bar lines, symbols on
223 The @code{\mark} command is primarily used for @ref{Rehearsal
224 marks}, but it can also be used to add text elements in a score:
226 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
230 As it can contain a @code{\markup} object, the @code{\mark} command
231 makes possible to put any text, but also signs like coda, segno, or
232 fermata on a bar line. The appropriate symbol has to be specified in
233 the @code{\markup} block; these symbols are listed in @ref{The Feta font}.
235 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
236 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
241 @code{\mark} is only typeset above the top staff of the score. If
242 you specify the @code{\mark} command at a bar line, the resulting
243 mark is placed above the bar line. If you specify it in the
244 middle of a bar, the resulting mark is positioned between notes.
245 If it is specified before the beginning of a score line, it is
246 placed before the first note of the line. Finally, if the mark
247 occurs at a line break, the mark will be printed at the beginning
250 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
251 @c delete this sentence. -gp
253 If there is no next line, then the mark will not be printed at
259 @c TODO: to be LSR-ized stuff -vv
261 To print the mark at the end of the current line, use
264 \override Score.RehearsalMark
265 #'break-visibility = #begin-of-line-invisible
268 @code{\mark} is often useful for adding text to the end of bar.
269 In such cases, changing the @code{#'self-alignment} is very useful
271 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
272 \override Score.RehearsalMark
273 #'break-visibility = #begin-of-line-invisible
275 \once \override Score.RehearsalMark #'self-alignment-X = #right
276 \mark "D.S. al Fine "
279 Text marks may be aligned with notation objects other than bar
282 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
287 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
291 \override Score.RehearsalMark #'break-align-symbols = #'(clef)
295 \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
304 Possible symbols for the @code{break-align-symbols} list are
305 @code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
306 @code{staff-bar}, @code{left-edge}, @code{key-cancellation},
307 @code{key-signature}, and @code{time-signature}.
309 The text marks will, by default, be aligned with the middle of the
310 notation object, but this can be changed by overriding the
311 @code{break-align-anchor-alignment} and @code{break-align-anchor}
312 properties for the appropriate grob. For scores with multiple staves,
313 this setting should be done for all the staves.
315 @lilypond[fragment,quote,ragged-right,verbatim]
317 \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
321 % the RehearsalMark will be aligned with the left edge of the KeySignature
322 \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
327 % the RehearsalMark will be aligned with the right edge of the KeySignature
328 \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
333 % the RehearsalMark will be aligned with the left edge of the KeySignature
334 % and then shifted right by 2 units.
335 \once \override Score.KeySignature #'break-align-anchor = #2
341 Although text marks are normally only printed above the topmost
342 staff, you may alter this to print them on every staff,
344 @lilypond[quote,ragged-right,verbatim,relative=2]
347 \remove "Mark_engraver"
351 \consists "Mark_engraver"
353 { c''1 \mark "foo" c'' }
355 \consists "Mark_engraver"
357 { c'1 \mark "foo" c' }
365 Snippets: @lsrdir{Text,Text}
367 Internals Reference: @internalsref{RehearsalMark}.
369 @c TODO: add this here? -vv
371 @c @subsubsection Text marks
374 @subsection Text markup
377 * Text markup introduction::
379 * Page wrapping text::
383 @node Text markup introduction
384 @subsubsection Text markup introduction
391 Use @code{\markup} to typeset text. Commands are entered with the
392 backslash @code{\}. To enter @code{\} and @code{#}, use double
395 @lilypond[quote,verbatim,fragment,relative=1]
397 c1_\markup { hi there }
398 c1^\markup { hi \bold there, is \italic {anyone home?} }
399 c1_\markup { "\special {weird} #characters" }
403 See @ref{Overview of text markup commands}, for a list of all
406 @code{\markup} is primarily used for @internalsref{TextScript}s,
407 but it can also be used anywhere text is called in lilypond
409 @lilypond[quote,verbatim]
410 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
413 \override Score.RehearsalMark
414 #'break-visibility = #begin-of-line-invisible
415 \override Score.RehearsalMark #'self-alignment-X = #right
417 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
418 c2^\markup{ don't be \flat }
419 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
421 a2\mark \markup{ \large \bold Fine }
425 \addlyrics { bar, foo \markup{ \italic bar! } }
429 A @code{\markup} command can also be placed on its own, away from
430 any @code{\score} block, see @ref{Multiple scores in a book}.
432 @lilypond[quote,ragged-right,verbatim]
433 \markup{ Here is some text. }
436 @cindex font switching
438 The markup in the example demonstrates font switching commands.
439 The command @code{\bold} and @code{\italic} apply to the first
440 following word only; to apply a command to more than one word,
441 enclose the words with braces,
444 \markup @{ \bold @{ hi there @} @}
448 For clarity, you can also do this for single arguments, e.g.,
451 \markup @{ is \italic @{ anyone @} home @}
454 In markup mode you can compose expressions, similar to
455 mathematical expressions, XML documents, and music expressions.
456 You can stack expressions grouped vertically with the command
457 @code{\column}. Similarly, @code{\center-align} aligns texts by
460 @lilypond[quote,verbatim,fragment,relative=1]
461 c1^\markup { \column { a bbbb \line { c d } } }
462 c1^\markup { \center-align { a bbbb c } }
463 c1^\markup { \line { a b c } }
466 Lists with no previous command are not kept distinct. The
470 \center-align @{ @{ a b @} @{ c d @} @}
478 \center-align @{ a b c d @}
483 To keep lists of words distinct, please use quotes @code{"} or
484 the @code{\line} command
486 @lilypond[quote,verbatim,fragment,relative=1]
488 c4^\markup{ \center-align { on three lines } }
489 c4^\markup{ \center-align { "all one line" } }
490 c4^\markup{ \center-align { { on three lines } } }
491 c4^\markup{ \center-align { \line { on one line } } }
494 Markups can be stored in variables and these variables may be
495 attached to notes, like
498 allegro = \markup @{ \bold \large @{ Allegro @} @}
499 @{ a^\allegro b c d @}
502 Some objects have alignment procedures of their own, which cancel
503 out any effects of alignments applied to their markup arguments as
504 a whole. For example, the @internalsref{RehearsalMark} is
505 horizontally centered, so using @code{\mark \markup @{ \left-align
506 .. @}} has no effect.
508 In addition, vertical placement is performed after creating the
509 text markup object. If you wish to move an entire piece of
510 markup, you need to use the #'padding property or create an
511 @q{anchor} point inside the markup (generally with @code{\hspace
514 @lilypond[quote,verbatim,fragment,relative=1]
516 c'4^\markup{ \raise #5 "not raised" }
517 \once \override TextScript #'padding = #3
518 c'4^\markup{ raised }
519 c'4^\markup{ \hspace #0 \raise #1.5 raised }
522 Some situations (such as dynamic marks) have preset font-related
523 properties. If you are creating text in such situations, it is
524 advisable to cancel those properties with @code{normal-text}. See
525 @ref{Overview of text markup commands}, for more details.
530 This manual: @ref{Overview of text markup commands}.
532 Snippets: @lsrdir{Text,Text}
534 Internals Reference: @internalsref{TextScript}.
536 Init files: @file{scm/@/new@/-markup@/.scm}.
541 Kerning or generation of ligatures is only done when the @TeX{}
542 backend is used. In this case, LilyPond does not account for them
543 so texts will be spaced slightly too wide.
545 Syntax errors for markup mode are confusing.
549 @subsubsection Nested scores
551 It is possible to nest music inside markups, by adding a
552 @code{\score} block to a markup expression. Such a score must
553 contain a @code{\layout} block.
555 @lilypond[quote,verbatim,ragged-right]
559 \relative { c4 d e f }
569 Snippets: @lsrdir{Text,Text}
571 @node Page wrapping text
572 @subsubsection Page wrapping text
574 Whereas @code{\markup} is used to enter a non-breakable block of
575 text, @code{\markuplines} can be used at top-level to enter lines
576 of text that can spread over multiple pages:
581 A very long text of justified lines.
585 An other very long paragraph.
592 @code{\markuplines} accepts a list of markup, that is either the
593 result of a markup list command, or a list of markups or of markup
594 lists. The built-in markup list commands are described in
595 @ref{Overview of text markup list commands}.
599 This manual: @ref{Overview of text markup list commands}, @ref{New
600 markup list command definition}.
602 Snippets: @lsrdir{Text,Text}
606 @funindex \markuplines
610 @subsubsection Font selection
612 @cindex font selection
613 @cindex font magnification
614 @funindex font-interface
616 By setting the object properties described below, you can select a
617 font from the preconfigured font families. LilyPond has default
618 support for the feta music fonts. Text fonts are selected through
619 Pango/FontConfig. The serif font defaults to New Century
620 Schoolbook, the sans and typewriter to whatever the Pango
621 installation defaults to.
625 @item @code{font-encoding}
626 is a symbol that sets layout of the glyphs. This should only be
627 set to select different types of non-text fonts, e.g.
629 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
630 standard music font, including ancient glyphs, @code{fetaDynamic}
631 for dynamic signs and @code{fetaNumber} for the number font.
633 @item @code{font-family}
634 is a symbol indicating the general class of the typeface.
635 Supported are @code{roman} (Computer Modern), @code{sans}, and
638 @item @code{font-shape}
639 is a symbol indicating the shape of the font. There are typically
640 several font shapes available for each font family. Choices are
641 @code{italic}, @code{caps}, and @code{upright}.
643 @item @code{font-series}
644 is a symbol indicating the series of the font. There are
645 typically several font series for each font family and shape.
646 Choices are @code{medium} and @code{bold}.
650 Fonts selected in the way sketched above come from a predefined
651 style sheet. If you want to use a font from outside the style
652 sheet, then set the @code{font-name} property,
654 @lilypond[fragment,verbatim]
656 \override Staff.TimeSignature #'font-name = #"Charter"
657 \override Staff.TimeSignature #'font-size = #2
660 \override #'(font-name . "Vera Bold")
661 { This text is in Vera Bold }
667 Any font can be used, as long as it is available to
668 Pango/FontConfig. To get a full list of all available fonts, run
672 lilypond -dshow-available-fonts blabla
675 (the last argument of the command can be anything, but has to be
679 The size of the font may be set with the @code{font-size}
680 property. The resulting size is taken relative to the
681 @code{text-font-size} as defined in the @code{\paper} block.
684 @cindex font magnification
687 It is also possible to change the default font family for the
688 entire document. This is done by calling the
689 @code{make-pango-font-tree} from within the @code{\paper} block.
690 The function takes names for the font families to use for roman,
691 sans serif and monospaced text. For example,
693 @cindex font families, setting
702 (make-pango-font-tree "Times New Roman"
709 c'^\markup { roman: foo \sans bla \typewriter bar }
713 @c we don't do Helvetica / Courier, since GS incorrectly loads
720 Snippets: @lsrdir{Text,Text}
723 @node Special text concerns
724 @subsection Special text concerns
726 @c FIXME: this section is to be removed
727 @c (see comments below) -vv
730 * New dynamic marks::
731 * Text and line spanners::
734 @node New dynamic marks
735 @subsubsection New dynamic marks
737 @c FIXME: this whole section should be removed and put in
738 @c "Writing text" -vv
740 It is possible to print new dynamic marks or text that should be
741 aligned with dynamics. Use @code{make-dynamic-script} to create
742 these marks. Note that the dynamic font only contains the
743 characters @code{f,m,p,r,s} and @code{z}.
745 Some situations (such as dynamic marks) have preset font-related
746 properties. If you are creating text in such situations, it is
747 advisable to cancel those properties with @code{normal-text}. See
748 @ref{Overview of text markup commands}, for more details.
750 @cindex make-dynamic-script
752 @lilypond[quote,verbatim,ragged-right]
753 sfzp = #(make-dynamic-script "sfzp")
759 @cindex Dynamics, editorial
760 @cindex Dynamics, parenthesis
762 It is also possible to print dynamics in round parenthesis or
763 square brackets. These are often used for adding editorial
766 @lilypond[quote,verbatim,ragged-right]
767 rndf = \markup{ \center-align {\line { \bold{\italic (}
768 \dynamic f \bold{\italic )} }} }
769 boxf = \markup{ \bracket { \dynamic f } }
770 { c'1_\rndf c'1_\boxf }
775 Snippets: @lsrdir{Text,Text}
778 @node Text and line spanners
779 @subsubsection Text and line spanners
781 @c FIXME: this whole section has to be removed.
782 @c glissando stuff should go into Expressive marks;
783 @c Text spanners should go into... Text spanners.
786 Some performance indications, e.g., @i{rallentando} and
787 @i{accelerando} and @i{trills} are written as text and are
788 extended over many measures with lines, sometimes dotted or wavy.
790 These all use the same routines as the glissando for drawing the
791 texts and the lines, and tuning their behavior is therefore also
792 done in the same way. It is done with a spanner, and the routine
793 responsible for drawing the spanners is
794 @code{ly:line-interface::print}. This routine determines the
795 exact location of the two @i{span points} and draws a line in
796 between, in the style requested.
798 Here is an example of the different line styles available, and how
801 @lilypond[relative=2,ragged-right,verbatim,fragment]
803 \once \override Glissando #'style = #'dashed-line
805 \override Glissando #'style = #'dotted-line
807 \override Glissando #'style = #'zigzag
809 \override Glissando #'style = #'trill
813 The information that determines the end-points is computed
814 on-the-fly for every graphic object, but it is possible to
817 @lilypond[relative=2,ragged-right,verbatim,fragment]
819 \once \override Glissando #'bound-details #'right #'Y = #-2
823 The @code{Glissando} object, like any other using the
824 @code{ly:line-interface::print} routine, carries a nested
825 association list. In the above statement, the value for @code{Y}
826 is set to @code{-2} for the association list corresponding to the
827 right end point. Of course, it is also possible to adjust the
828 left side with @code{left} instead of @code{right}.
830 If @code{Y} is not set, the value is computed from the vertical
831 position of right attachment point of the spanner.
833 In case of a line break, the values for the span-points are
834 extended with contents of the @code{left-broken} and
835 @code{right-broken} sublists, for example
837 @lilypond[relative=2,ragged-right,verbatim,fragment]
838 \override Glissando #'breakable = ##T
839 \override Glissando #'bound-details #'right-broken #'Y = #-3
844 The following properties can be used for the
848 This sets the Y-coordinate of the end point, in staff space. By
849 default, it is the center of the bound object, so for a glissando
850 it points to the vertical center of the note head.
852 For horizontal spanners, such as text spanner and trill spanners,
853 it is hardcoded to 0.
856 This determines where the line starts and ends in X-direction,
857 relative to the bound object. So, a value of @code{-1} (or
858 @code{LEFT}) makes the line start/end at the left side of the note
859 head it is attached to.
862 This is the absolute coordinate of the end point. It is usually
863 computed on the fly, and there is little use in overriding it.
866 Line spanners may have symbols at the beginning or end, which is
867 contained in this sub-property. This is for internal use, it is
868 recommended to use @code{text}.
871 This is a markup that is evaluated to yield stencil. It is used
872 to put @i{cresc.} and @i{tr} on horizontal spanners.
874 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
875 \override TextSpanner #'bound-details #'left #'text
876 = \markup { \small \bold Slower }
877 c2\startTextSpan b c a\stopTextSpan
880 @item stencil-align-dir-y
882 Without setting this, the stencil is simply put there at the
883 end-point, as defined by the @code{X} and @code{Y} sub properties.
884 Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
885 will move the symbol at the edge relative to the end point of the
888 @lilypond[relative=1,fragment,verbatim]
889 \override TextSpanner #'bound-details
890 #'left #'stencil-align-dir-y = #DOWN
891 \override TextSpanner #'bound-details
892 #'right #'stencil-align-dir-y = #UP
894 \override TextSpanner #'bound-details
895 #'left #'text = #"gggg"
896 \override TextSpanner #'bound-details
897 #'right #'text = #"hhhh"
898 c4^\startTextSpan c c c \stopTextSpan
902 Setting this sub property to @code{#t} produce an arrowhead at the
906 This sub property controls the space between the specified
907 end-point of the line and the actual end. Without padding, a
908 glissando would start and end in the center of each note head.
912 TODO: add this somewhere
916 \override TextSpanner #'bound-details #'left-broken #'text = ##f
917 \override TextSpanner #'bound-details #'left #'text = \markup {
919 c'1 \startTextSpan \break
926 The music function \endSpanners terminates spanners and hairpins
927 after exactly one note.
929 @lilypond[verbatim,quote,ragged-right,relative=2,fragment]
935 When using \endSpanners it is not necessary to close
936 \startTextSpan with \stopTextSpan, nor is it necessary to close
943 Snippets: @lsrdir{Text,Text}
945 Internals Reference: @internalsref{TextSpanner},
946 @internalsref{Glissando}, @internalsref{VoiceFollower},
947 @internalsref{TrillSpanner},
948 @internalsref{line-spanner-interface}.