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 Vivo }
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. }
532 Some of these font families, used for specific items
533 such as numbers or dynamics, do not provide all
534 characters, as mentioned in @ref{New dynamic marks} and
535 @ref{Manual repeat marks}.
538 Defining custom font sets is also possible, as explained in
541 An exhaustive list of font-switching, font-size and font-families related
542 commands can be found in @ref{Font}.
544 @c TODO: add @seealso
547 When used inside a word, some of these commands may produce an unwanted
548 blank space. This can easily be solved by concatenating the text
549 elements together, using a specific command
550 described in @ref{Text alignment}.
555 @subsubsection Text alignment
557 @warning{This subsection discusses how to place text in markup mode,
558 inside a @code{\markup} block. However, markup objects can also
559 be moved as a whole using the syntax described in
560 @rlearning{Moving objects}.}
562 Markup objects can be aligned in different ways. By default,
563 a text indication is aligned on its left edge: in the following
564 example, there's no difference between the first and the second
567 @lilypond[quote,verbatim,fragment,relative=1]
570 a,-\markup { \left-align poco }
572 a,-\markup { \center-align { poco } }
574 a,-\markup { \right-align poco }
577 @c FIXME: \center-align actually doesn't belong here
578 @c \center-align vs \column
579 @c \center-align vs \hcenter
581 Horizontal alignment:
603 Building a "large" markup:
616 Alignment inside a "large" markup:
628 TODO: here are some commands that could be described here.
629 I'm putting them in bulk, prior to working on this section. -vv
641 \page-ref (see also "Table of contents")
654 Some objects have alignment procedures of their own, which cancel
655 out any effects of alignments applied to their markup arguments as
656 a whole. For example, the @rinternals{RehearsalMark} is
657 horizontally centered, so using @code{\mark \markup @{ \left-align
658 .. @}} has no effect.
662 @node Graphic notation inside markup
663 @subsubsection Graphic notation inside markup
664 Graphics around text:
671 "Standalone" graphics:
691 @node Music notation inside markup
692 @subsubsection Music notation inside markup
694 Notes can be printed in markup mode blah blah:
699 Accidental symbols can be obtained easily:
711 Some other notation objects blah blah
719 @c TODO: add \text here? -vv
721 Any musical symbol can be printed
724 @c TODO: add \lookup here? -vv
727 The markup mode has support for fret diagrams:
731 \fret-diagram-verbose
733 An entire @code{\score} block can even be nested in a @code{\markup}
734 block. In such a case, the @code{\score} must contain a @code{\layout} block.
740 @lilypond[quote,verbatim,ragged-right]
744 \relative { c4 d e f }
757 @node Multi-page markup
758 @subsubsection Multi-page markup
760 Whereas @code{\markup} is used to enter a non-breakable block of
761 text, @code{\markuplines} can be used at top-level to enter lines
762 of text that can spread over multiple pages:
767 A very long text of justified lines.
771 An other very long paragraph.
778 @code{\markuplines} accepts a list of markup, that is either the
779 result of a markup list command, or a list of markups or of markup
780 lists. The built-in markup list commands are described in
781 @ref{Text markup list commands}.
785 This manual: @ref{Text markup list commands}, @ref{New
786 markup list command definition}.
793 @funindex \markuplines
801 * Entire document fonts::
802 * Single entry fonts::
805 @node Entire document fonts
806 @subsubsection Entire document fonts
808 It is also possible to change the default font family for the
809 entire document. This is done by calling the
810 @code{make-pango-font-tree} from within the @code{\paper} block.
811 The function takes names for the font families to use for roman,
812 sans serif and monospaced text. For example,
814 @cindex font families, setting
823 (make-pango-font-tree "Times New Roman"
830 c'^\markup { roman: foo \sans bla \typewriter bar }
834 @c we don't do Helvetica / Courier, since GS incorrectly loads
838 @node Single entry fonts
839 @subsubsection Single entry fonts
841 @cindex font selection
842 @cindex font magnification
843 @funindex font-interface
845 By setting the object properties described below, you can select a
846 font from the preconfigured font families. LilyPond has default
847 support for the feta music fonts. Text fonts are selected through
848 Pango/FontConfig. The serif font defaults to New Century
849 Schoolbook, the sans and typewriter to whatever the Pango
850 installation defaults to.
854 @item @code{font-encoding}
855 is a symbol that sets layout of the glyphs. This should only be
856 set to select different types of non-text fonts, e.g.
858 @code{fetaBraces} for piano staff braces, @code{fetaMusic} the
859 standard music font, including ancient glyphs, @code{fetaDynamic}
860 for dynamic signs and @code{fetaNumber} for the number font.
862 @item @code{font-family}
863 is a symbol indicating the general class of the typeface.
864 Supported are @code{roman} (Computer Modern), @code{sans}, and
867 @item @code{font-shape}
868 is a symbol indicating the shape of the font. There are typically
869 several font shapes available for each font family. Choices are
870 @code{italic}, @code{caps}, and @code{upright}.
872 @item @code{font-series}
873 is a symbol indicating the series of the font. There are
874 typically several font series for each font family and shape.
875 Choices are @code{medium} and @code{bold}.
879 Fonts selected in the way sketched above come from a predefined
880 style sheet. If you want to use a font from outside the style
881 sheet, then set the @code{font-name} property,
883 @lilypond[fragment,verbatim]
885 \override Staff.TimeSignature #'font-name = #"Charter"
886 \override Staff.TimeSignature #'font-size = #2
889 \override #'(font-name . "Vera Bold")
890 { This text is in Vera Bold }
896 Any font can be used, as long as it is available to
897 Pango/FontConfig. To get a full list of all available fonts, run
901 lilypond -dshow-available-fonts blabla
904 (the last argument of the command can be anything, but has to be
908 The size of the font may be set with the @code{font-size}
909 property. The resulting size is taken relative to the
910 @code{text-font-size} as defined in the @code{\paper} block.
913 @cindex font magnification