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
57 It is possible to add arbitrary text indications
58 to a score, as demonstrated in the following example.
59 Such indications can also be manually placed
60 above or below the staff, using the
61 simple syntax described in @ref{Controlling direction and
64 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
65 d8^"pizz." e f g a4-"scherz." f
68 In LilyPond, such text strings are called @command{markup}
69 objects. 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]
84 d8^"pizz." e f g \textLengthOn a4_"scherzando" f
89 @funindex \textLengthOn
91 @funindex \textLengthOff
97 Notation Reference: @ref{Formatting text},
98 @ref{Controlling direction and placement}.
103 Internals Reference: @rinternals{TextScript}.
107 Checking to make sure that text scripts and lyrics are within the
108 margins is a relatively large computational task. To speed up
109 processing, LilyPond does not perform such calculations by
110 default; to enable it, use
113 \override Score.PaperColumn #'keep-inside-line = ##t
118 @subsubsection Text spanners
120 @cindex Text spanners
122 Some performance indications, e.g., @i{rallentando} or
123 @i{accelerando}, are written as text and are extended over many
124 measures with dotted lines.
125 Such objects, called @q{spanners}, may be created
126 from one note to another using the following syntax:
128 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
129 \override TextSpanner #'bound-details #'left #'text = "rit."
135 The string to be printed is set through
136 object properties. By default it is printed in italic characters,
137 but different formatting can be obtained using
138 @code{\markup} blocks, as described in @ref{Formatting text}.
140 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
141 \override TextSpanner #'bound-details #'left #'text =
142 \markup { \upright "rit." }
147 The line style, as well as the text string, can be defined as an
148 object property. This syntax is described in @ref{Line styles}.
152 @funindex textSpannerUp
153 @code{\textSpannerUp},
154 @funindex textSpannerDown
155 @code{\textSpannerDown},
156 @funindex textSpannerNeutral
157 @code{\textSpannerNeutral}
161 Notation Reference: @ref{Line styles}.
166 Internals Reference: @rinternals{TextSpanner}.
170 @subsubsection Text marks
172 @cindex coda on bar line
173 @cindex segno on bar line
174 @cindex fermata on bar line
175 @cindex bar lines, symbols on
178 Various text elements can be added to a score using
179 the syntax described in @ref{Rehearsal marks}:
181 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
182 c4\mark "Allegro" c c c
185 This syntax makes possible to put any text on a bar line;
186 more complex text formatting may be added using a @code{\markup}
187 block, as described in @ref{Formatting text}. This can be used to print
188 signs like coda, segno or fermata, by specifying the appropriate
191 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
192 c1 \mark \markup { \musicglyph #"scripts.ufermata" }
197 Such objects are only typeset above the top staff of the score; depending on
198 whether they are specified at the end or the middle of a bar, they
199 can be placed above the bar line or between notes. When specified at the
200 beginning of a score or at a line break, marks will be printed at
201 the beginning of the line (the next line, in case of a line break).
203 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
205 c\mark "assai" \break
212 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
213 {printing-marks-at-the-end-of-a-line-or-a-score.ly}
215 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
216 {aligning-marks-with-various-notation-objects.ly}
218 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc]
219 {printing-marks-on-every-staff.ly}
223 Notation Reference: @ref{Rehearsal marks},
224 @ref{Formatting text}, @ref{The Feta font}.
229 Internals Reference: @rinternals{RehearsalMark}.
232 @c IMO this is a bug; hopefully it'll be fixed soon, so I can
233 @c delete this sentence. -gp
234 @c A workaround is suggested in the first @snippets item -vv
236 If a mark is entered at the end of the last bar of the score (where
237 there is no next line), then the mark will not be printed at
241 @subsubsection Separate text
243 @cindex separate text
244 @cindex standalone text
245 @cindex top-level text
246 @cindex text, standalone
249 A @code{\markup} block can exist by itself, outside of any
250 any @code{\score} block, as a @qq{top-level
251 expression}. This syntax is described in @ref{File structure}.
253 @lilypond[quote,ragged-right,verbatim]
255 Tomorrow, and tomorrow, and tomorrow...
260 This allows to print text separately
261 from the music, which is particularly
262 useful when the input file contains
263 several music pieces, as described in
264 @ref{Multiple scores in a book}.
266 @lilypond[quote,ragged-right,verbatim]
271 Tomorrow, and tomorrow, and tomorrow...
278 Using a specific syntax, text blocks can be spread
279 over multiple pages, making possible to print
280 text documents or books -- and therefore to
281 use LilyPond as a word processor. This syntax is described in
282 @ref{Multi-page markup}.
288 @funindex \markuplines
294 TODO: add convenient snippets in input/new -vv
299 Notation Reference: @ref{Formatting text},
300 @ref{File structure},
301 @ref{Multiple scores in a book},
302 @ref{Multi-page markup}.
307 Internals Reference: @rinternals{TextScript}.
310 @node Formatting text
311 @subsection Formatting text
313 This section presents basic and advanced text formatting,
314 using the @code{\markup} mode specific syntax.
317 * Text markup introduction::
318 * Common markup commands::
320 * Graphic notation inside markup::
321 * Music notation inside markup::
322 * Multi-page markup::
325 @node Text markup introduction
326 @subsubsection Text markup introduction
333 A @code{\markup} block is used to typeset text with an extensible
334 specific syntax called @qq{markup mode}.
336 @c TODO: make a nicer example (maybe ask Trevor B?) -vv
337 @lilypond[quote,verbatim]
338 \header{ title = \markup{ \bold { foo \italic { bar! } } } }
341 \override Score.RehearsalMark
342 #'break-visibility = #begin-of-line-invisible
343 \override Score.RehearsalMark #'self-alignment-X = #right
345 \set Staff.instrumentName = \markup{ \column{ Alto solo } }
346 c2^\markup{ don't be \flat }
347 \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
349 a2\mark \markup{ \large \bold Fine }
353 \addlyrics { bar, foo \markup{ \italic bar! } }
357 @cindex markup expressions
358 @cindex markup syntax
360 The markup syntax is similar to LilyPond's usual syntax: a
361 @code{\markup} expression can be made of one word, or several words.
362 In the latter case, the expression has to be enclosed in curly braces
363 @code{@{ ... @}} or double quotes @code{"..."}.
365 While a text string between double quotes is regarded as an indivisible
366 single expression, markup blocks defined using braces can contain
369 In markup mode, specific commands are entered using the
370 backslash @code{\} character. Such commands only affect
371 the first following expression: either a single word, or
374 @lilypond[quote,verbatim,fragment,relative=1]
376 a2^\markup { poco \italic più forte }
378 d2_\markup { \italic "string. assai" }
380 b1^\markup { \bold { molto agitato } }
385 In this example, the first markup is made of one word without any
386 braces or quotes, while the following markups demonstrate the usefulness
387 of nested markup expressions using braces.
388 This syntax is prefered, as it allows both single-word and multi-word
391 @cindex special characters in markup mode
392 @cindex markup mode, special characters
393 @cindex reserved characters, printing
394 @cindex printing special characters
396 Special characters such as @code{\} and @code{#}
397 can be printed in the output simply using double
398 quotes. Double quotation marks are only printed
399 in the output when preceded by backslashes:
401 @lilypond[quote,verbatim,fragment,relative=1]
403 a^\markup "##\ LEPORELLO \##"
404 a_\markup "Bravi! \"Cosa rara\"!"
409 The way markup expressions are defined affects
410 how these expressions will stacked,centered and aligned;
411 this syntax is described in @ref{Text alignment}.
413 @lilypond[quote,verbatim,fragment,relative=1]
414 c1^\markup { \column { a bbbb \line { c d } } }
415 c1^\markup { \center-align { a bbbb c } }
416 c1^\markup { \line { a b c } }
419 Lists of words that are not enclosed with double quotes
420 or preceded by a previous command are not kept distinct. In
421 the following example, the first two @code{\markup} expressions
424 @lilypond[quote,verbatim,fragment,relative=1]
425 c1^\markup { \center-align { a bbb c } }
426 c1^\markup { \center-align { a { bbb c } } }
427 c1^\markup { \center-align { a \line { bbb c } } }
431 Markups can be stored in variables. These variables may be
434 @lilypond[quote,verbatim]
435 allegro = \markup { \bold \large Allegro }
445 An exhaustive list of @code{\markup}-specific commands can be found in
446 @ref{Text markup commands}.
449 TODO: here are some commands that could be described here.
450 I'm putting them in bulk, prior to working on this section. -vv
462 \page-ref (see also "Table of contents")
486 This manual: @ref{Text markup commands}.
491 Internals Reference: @rinternals{TextScript}.
493 Init files: @file{scm/@/new@/-markup@/.scm}.
498 Kerning or generation of ligatures is only done when the @TeX{}
499 backend is used. In this case, LilyPond does not account for them
500 so texts will be spaced slightly too wide.
502 Syntax errors for markup mode are confusing.
504 @node Common markup commands
505 @subsubsection Common markup commands
507 Some basic formatting can be used blah blah
510 @cindex font switching
512 Some font switching commands are demonstrated here.
521 @c TODO: what's the difference between the following commands? -vv
527 Some alternate font families can easily be selected:
532 \number (only for numbers, such as fingerings and time signatures)
533 @c TODO: add \slashed-digit here? -vv
535 The size can be blah blah blah
539 Some predefined font sizes can be used blah blah
548 Some shorcuts allow to change the font size relatively to its previous value
556 Text may be printed as subscript or superscript:
561 To obtain subscripts or superscripts in a normal text size, use
565 All these settings (except the size) can be reverted to the default font:
571 @subsubsection Text alignment
574 Some objects have alignment procedures of their own, which cancel
575 out any effects of alignments applied to their markup arguments as
576 a whole. For example, the @rinternals{RehearsalMark} is
577 horizontally centered, so using @code{\mark \markup @{ \left-align
578 .. @}} has no effect.
580 In addition, vertical placement is performed after creating the
581 text markup object. If you wish to move an entire piece of
582 markup, you need to use the #'padding property or create an
583 @q{anchor} point inside the markup (generally with @code{\hspace
586 @lilypond[quote,verbatim,fragment,relative=1]
588 c'4^\markup{ \raise #5 "not raised" }
589 \once \override TextScript #'padding = #3
590 c'4^\markup{ raised }
591 c'4^\markup{ \hspace #0 \raise #1.5 raised }
594 Some situations (such as dynamic marks) have preset font-related
595 properties. If you are creating text in such situations, it is
596 advisable to cancel those properties with @code{normal-text}. See
597 @ref{Text markup commands}, for more details.
605 Horizontal alignment:
616 Building a "large" markup:
629 Alignment inside a "large" markup:
639 @node Graphic notation inside markup
640 @subsubsection Graphic notation inside markup
641 Graphics around text:
648 "Standalone" graphics:
668 @node Music notation inside markup
669 @subsubsection Music notation inside markup
671 Notes can be printed in markup mode blah blah:
676 Accidental symbols can be obtained easily:
688 Some other notation objects blah blah
696 @c TODO: add \text here? -vv
698 Any musical symbol can be printed
701 @c TODO: add \lookup here? -vv
704 The markup mode has support for fret diagrams:
708 \fret-diagram-verbose
710 An entire @code{\score} block can even be nested in a @code{\markup}
711 block. In such a case, the @code{\score} must contain a @code{\layout} block.
717 @lilypond[quote,verbatim,ragged-right]
721 \relative { c4 d e f }
734 @node Multi-page markup
735 @subsubsection Multi-page markup
737 Whereas @code{\markup} is used to enter a non-breakable block of
738 text, @code{\markuplines} can be used at top-level to enter lines
739 of text that can spread over multiple pages:
744 A very long text of justified lines.
748 An other very long paragraph.
755 @code{\markuplines} accepts a list of markup, that is either the
756 result of a markup list command, or a list of markups or of markup
757 lists. The built-in markup list commands are described in
758 @ref{Text markup list commands}.
762 This manual: @ref{Text markup list commands}, @ref{New
763 markup list command definition}.
770 @funindex \markuplines
775 @c TODO: move the following subsubsec into NR3 -vv
781 * Entire document fonts::
782 * Single entry fonts::
785 @node Entire document fonts
786 @subsubsection Entire document fonts
788 It is also possible to change the default font family for the
789 entire document. This is done by calling the
790 @code{make-pango-font-tree} from within the @code{\paper} block.
791 The function takes names for the font families to use for roman,
792 sans serif and monospaced text. For example,
794 @cindex font families, setting
803 (make-pango-font-tree "Times New Roman"
810 c'^\markup { roman: foo \sans bla \typewriter bar }
814 @c we don't do Helvetica / Courier, since GS incorrectly loads
818 @node Single entry fonts
819 @subsubsection Single entry fonts
821 @cindex font selection
822 @cindex font magnification
823 @funindex font-interface
825 By setting the object properties described below, you can select a
826 font from the preconfigured font families. LilyPond has default
827 support for the feta music fonts. Text fonts are selected through
828 Pango/FontConfig. The serif font defaults to New Century
829 Schoolbook, the sans and typewriter to whatever the Pango
830 installation defaults to.
834 @item @code{font-encoding}
835 is a symbol that sets layout of the glyphs. This should only be
836 set to select different types of non-text fonts, e.g.
838 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
839 standard music font, including ancient glyphs, @code{fetaDynamic}
840 for dynamic signs and @code{fetaNumber} for the number font.
842 @item @code{font-family}
843 is a symbol indicating the general class of the typeface.
844 Supported are @code{roman} (Computer Modern), @code{sans}, and
847 @item @code{font-shape}
848 is a symbol indicating the shape of the font. There are typically
849 several font shapes available for each font family. Choices are
850 @code{italic}, @code{caps}, and @code{upright}.
852 @item @code{font-series}
853 is a symbol indicating the series of the font. There are
854 typically several font series for each font family and shape.
855 Choices are @code{medium} and @code{bold}.
859 Fonts selected in the way sketched above come from a predefined
860 style sheet. If you want to use a font from outside the style
861 sheet, then set the @code{font-name} property,
863 @lilypond[fragment,verbatim]
865 \override Staff.TimeSignature #'font-name = #"Charter"
866 \override Staff.TimeSignature #'font-size = #2
869 \override #'(font-name . "Vera Bold")
870 { This text is in Vera Bold }
876 Any font can be used, as long as it is available to
877 Pango/FontConfig. To get a full list of all available fonts, run
881 lilypond -dshow-available-fonts blabla
884 (the last argument of the command can be anything, but has to be
888 The size of the font may be set with the @code{font-size}
889 property. The resulting size is taken relative to the
890 @code{text-font-size} as defined in the @code{\paper} block.
893 @cindex font magnification