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
58 Simple @q{quoted text} indications may be added
59 to a score, as demonstrated in the following example.
60 Such indications can be manually placed
61 above or below the staff, using the
62 simple syntax described in @ref{Direction and
65 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
66 d8^"pizz." e f g a4-"scherz." f
69 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{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,doctitle]
213 {printing-marks-at-the-end-of-a-line-or-a-score.ly}
215 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
216 {aligning-marks-with-various-notation-objects.ly}
218 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
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 To be removed when Issue 69 in the tracker gets fixed. -vv
234 If a mark is entered at the end of the last bar of the score (where
235 there is no next line), then the mark will not be printed at
239 @subsubsection Separate text
241 @cindex separate text
242 @cindex standalone text
243 @cindex top-level text
244 @cindex text, standalone
247 A @code{\markup} block can exist by itself, outside of any
248 any @code{\score} block, as a @qq{top-level
249 expression}. This syntax is described in @ref{File structure}.
251 @lilypond[verbatim,quote]
253 Tomorrow, and tomorrow, and tomorrow...
258 This allows to print text separately
259 from the music, which is particularly
260 useful when the input file contains
261 several music pieces, as described in
262 @ref{Multiple scores in a book}.
264 @lilypond[quote,ragged-right,verbatim]
269 Tomorrow, and tomorrow, and tomorrow...
276 Using a specific syntax, text blocks can be spread
277 over multiple pages, making possible to print
278 text documents or books -- and therefore to
279 use LilyPond as a word processor. This syntax is described in
280 @ref{Multi-page markup}.
285 @funindex \markuplines
291 TODO: add convenient snippets in input/new -vv
296 Notation Reference: @ref{Formatting text},
297 @ref{File structure},
298 @ref{Multiple scores in a book},
299 @ref{Multi-page markup}.
304 Internals Reference: @rinternals{TextScript}.
307 @node Formatting text
308 @subsection Formatting text
310 This section presents basic and advanced text formatting,
311 using the @code{\markup} mode specific syntax.
314 * Text markup introduction::
315 * Common markup commands::
317 * Graphic notation inside markup::
318 * Music notation inside markup::
319 * Multi-page markup::
322 @node Text markup introduction
323 @subsubsection Text markup introduction
331 A @code{\markup} block is used to typeset text with an extensible
332 specific syntax called @qq{markup mode}.
334 @cindex markup expressions
335 @cindex markup syntax
337 The markup syntax is similar to LilyPond's usual syntax: a
338 @code{\markup} expression is enclosed in curly braces @code{@{
341 Unlike simple @q{quoted text} indications, @code{\markup} blocks
342 may contain nested expressions or specific commands,
343 entered using the backslash @code{\} character.
344 Such commands only affect the first following expression.
346 @lilypond[quote,verbatim,fragment,relative=1]
348 a2^\markup { poco \italic più forte }
350 d2_\markup { \italic "string. assai" }
352 b1^\markup { \bold { molto \italic agitato } }
356 @cindex special characters in markup mode
357 @cindex markup mode, special characters
358 @cindex reserved characters, printing
359 @cindex printing special characters
360 @cindex quoted text in markup mode
362 A @code{\markup} block may also contain quoted text, which
363 can be useful to print special characters (such as @code{\} and @code{#}).
364 Quoted text even allows to print double quotation marks, by preceding
365 them with backslashes:
367 @lilypond[quote,verbatim,fragment,relative=1]
369 a^\markup "##\ LEPORELLO \##"
370 a_\markup "Bravi! \"Cosa rara\"!"
375 The way markup expressions are defined affects
376 how these expressions will stacked, centered and aligned
377 when using the commands explained in @ref{Text alignment}.
379 @lilypond[quote,verbatim,fragment,relative=1]
380 c1^\markup { \column { a bbbb \line { c d } } }
381 c1^\markup { \center-align { a bbbb c } }
382 c1^\markup { \line { a b c } }
385 Lists of words that are not enclosed with double quotes
386 or preceded by a command are not kept distinct. In
387 the following example, the first two @code{\markup} expressions
390 @lilypond[quote,verbatim,fragment,relative=1]
391 c1^\markup { \center-align { a bbb c } }
392 c1^\markup { \center-align { a { bbb c } } }
393 c1^\markup { \center-align { a \line { bbb c } } }
397 Markups can be stored in variables. These variables may be
398 directly attached to notes:
400 @lilypond[quote,verbatim]
401 allegro = \markup { \bold \large Allegro }
411 An exhaustive list of @code{\markup}-specific commands can be found in
412 @ref{Text markup commands}.
417 This manual: @ref{Text markup commands}.
422 Internals Reference: @rinternals{TextScript}.
424 Init files: @file{scm/@/new@/-markup@/.scm}.
429 Syntax errors for markup mode are confusing.
432 @node Common markup commands
433 @subsubsection Common markup commands
435 Markup text may be formatted using simple commands.
437 @cindex font switching
442 Basic font switching is supported:
444 @lilypond[quote,verbatim,relative=2]
448 \italic { non troppo \underline Allegro }
451 d,_\markup { \italic quasi \smallCaps Tromba }
465 The size of the characters can also be altered in different ways:
468 the font size can be defined to an absolute value,
471 predefined commands allow to easily select standard sizes,
474 other commands allow to change the size relatively to its previous value.
478 The following example demonstrates these three methods:
480 @lilypond[quote,verbatim,relative=2]
482 f1^\markup { \fontsize #5 Sinfonia }
491 \magnify #0.6 {e sentimento } )
502 Text may be printed as subscript or superscript. By default
503 these are printed in a smaller size, but a normal size can be used as well:
505 @lilypond[quote,verbatim]
508 \line { 1 \super st movement }
509 \line { 1 \normal-size-super st movement
510 \sub { (part two) } }
515 The markup mode provides an easy way to select alternate
516 font families. The default serif font, of roman type, is automatically
517 selected unless specified otherwise: on the last line of the following example,
518 there is no difference between the first word and the following words.
520 @lilypond[quote,verbatim]
523 \line { Act \number 1 }
524 \line { \sans { Scene I. } }
525 \line { \typewriter { Verona. An open place. } }
526 \line { \roman Enter Valentine and Proteus. }
531 It is also possible to defined custom sets of fonts, as explained in
535 An exhaustive list of font-switching, font-size and font-families related
536 commands can be found in @ref{Font}.
539 When used inside a word, some of these commands may produce an unwanted
540 blank space. This can easily be solved by concatenating the text
541 elements together, using a specific command
542 described in @ref{Text alignment}.
547 @subsubsection Text alignment
550 Some objects have alignment procedures of their own, which cancel
551 out any effects of alignments applied to their markup arguments as
552 a whole. For example, the @rinternals{RehearsalMark} is
553 horizontally centered, so using @code{\mark \markup @{ \left-align
554 .. @}} has no effect.
556 In addition, vertical placement is performed after creating the
557 text markup object. If you wish to move an entire piece of
558 markup, you need to use the #'padding property or create an
559 @q{anchor} point inside the markup (generally with @code{\hspace
562 @lilypond[quote,verbatim,fragment,relative=1]
564 c'4^\markup{ \raise #5 "not raised" }
565 \once \override TextScript #'padding = #3
566 c'4^\markup{ raised }
567 c'4^\markup{ \hspace #0 \raise #1.5 raised }
570 Some situations (such as dynamic marks) have preset font-related
571 properties. If you are creating text in such situations, it is
572 advisable to cancel those properties with @code{normal-text}. See
573 @ref{Text markup commands}, for more details.
581 Horizontal alignment:
592 Building a "large" markup:
605 Alignment inside a "large" markup:
617 TODO: here are some commands that could be described here.
618 I'm putting them in bulk, prior to working on this section. -vv
630 \page-ref (see also "Table of contents")
653 @node Graphic notation inside markup
654 @subsubsection Graphic notation inside markup
655 Graphics around text:
662 "Standalone" graphics:
682 @node Music notation inside markup
683 @subsubsection Music notation inside markup
685 Notes can be printed in markup mode blah blah:
690 Accidental symbols can be obtained easily:
702 Some other notation objects blah blah
710 @c TODO: add \text here? -vv
712 Any musical symbol can be printed
715 @c TODO: add \lookup here? -vv
718 The markup mode has support for fret diagrams:
722 \fret-diagram-verbose
724 An entire @code{\score} block can even be nested in a @code{\markup}
725 block. In such a case, the @code{\score} must contain a @code{\layout} block.
731 @lilypond[quote,verbatim,ragged-right]
735 \relative { c4 d e f }
748 @node Multi-page markup
749 @subsubsection Multi-page markup
751 Whereas @code{\markup} is used to enter a non-breakable block of
752 text, @code{\markuplines} can be used at top-level to enter lines
753 of text that can spread over multiple pages:
758 A very long text of justified lines.
762 An other very long paragraph.
769 @code{\markuplines} accepts a list of markup, that is either the
770 result of a markup list command, or a list of markups or of markup
771 lists. The built-in markup list commands are described in
772 @ref{Text markup list commands}.
776 This manual: @ref{Text markup list commands}, @ref{New
777 markup list command definition}.
784 @funindex \markuplines
792 * Entire document fonts::
793 * Single entry fonts::
796 @node Entire document fonts
797 @subsubsection Entire document fonts
799 It is also possible to change the default font family for the
800 entire document. This is done by calling the
801 @code{make-pango-font-tree} from within the @code{\paper} block.
802 The function takes names for the font families to use for roman,
803 sans serif and monospaced text. For example,
805 @cindex font families, setting
814 (make-pango-font-tree "Times New Roman"
821 c'^\markup { roman: foo \sans bla \typewriter bar }
825 @c we don't do Helvetica / Courier, since GS incorrectly loads
829 @node Single entry fonts
830 @subsubsection Single entry fonts
832 @cindex font selection
833 @cindex font magnification
834 @funindex font-interface
836 By setting the object properties described below, you can select a
837 font from the preconfigured font families. LilyPond has default
838 support for the feta music fonts. Text fonts are selected through
839 Pango/FontConfig. The serif font defaults to New Century
840 Schoolbook, the sans and typewriter to whatever the Pango
841 installation defaults to.
845 @item @code{font-encoding}
846 is a symbol that sets layout of the glyphs. This should only be
847 set to select different types of non-text fonts, e.g.
849 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
850 standard music font, including ancient glyphs, @code{fetaDynamic}
851 for dynamic signs and @code{fetaNumber} for the number font.
853 @item @code{font-family}
854 is a symbol indicating the general class of the typeface.
855 Supported are @code{roman} (Computer Modern), @code{sans}, and
858 @item @code{font-shape}
859 is a symbol indicating the shape of the font. There are typically
860 several font shapes available for each font family. Choices are
861 @code{italic}, @code{caps}, and @code{upright}.
863 @item @code{font-series}
864 is a symbol indicating the series of the font. There are
865 typically several font series for each font family and shape.
866 Choices are @code{medium} and @code{bold}.
870 Fonts selected in the way sketched above come from a predefined
871 style sheet. If you want to use a font from outside the style
872 sheet, then set the @code{font-name} property,
874 @lilypond[fragment,verbatim]
876 \override Staff.TimeSignature #'font-name = #"Charter"
877 \override Staff.TimeSignature #'font-size = #2
880 \override #'(font-name . "Vera Bold")
881 { This text is in Vera Bold }
887 Any font can be used, as long as it is available to
888 Pango/FontConfig. To get a full list of all available fonts, run
892 lilypond -dshow-available-fonts blabla
895 (the last argument of the command can be anything, but has to be
899 The size of the font may be set with the @code{font-size}
900 property. The resulting size is taken relative to the
901 @code{text-font-size} as defined in the @code{\paper} block.
904 @cindex font magnification