]> git.donarmstrong.com Git - lilypond.git/blob - Documentation/user/text.itely
075bfdf23e4f876efcf016f96947c8dcd6f4b457
[lilypond.git] / Documentation / user / text.itely
1 @c -*- coding: utf-8; mode: texinfo; -*-
2 @ignore
3     Translation of GIT committish: FILL-IN-HEAD-COMMITTISH
4
5     When revising a translation, copy the HEAD committish of the
6     version that you are working on.  See TRANSLATION for details.
7 @end ignore
8
9 @c \version "2.11.57"
10
11 @node Text
12 @section Text
13
14 @lilypondfile[quote]{text-headword.ly}
15
16 This section explains how to include text (with various
17 formatting) in music scores.
18
19 @noindent
20 Some text elements that are not dealt with here are discussed in other
21 specific sections: @ref{Vocal music}, @ref{Titles and headers}.
22
23 @menu
24 * Writing text::                
25 * Formatting text::             
26 * Fonts::                       
27 @end menu
28
29 @cindex Text, other languages
30 @warning{To write accented and special text (such as characters
31 from other languages), simply insert the characters directly into
32 the LilyPond file.  The file must be saved as UTF-8.  For more
33 information, see @ref{Text encoding}.}
34
35 @node Writing text
36 @subsection Writing text
37
38 This section introduces different ways of adding text to a score.
39
40 @menu
41 * Text scripts::                
42 * Text spanners::               
43 * Text marks::                  
44 * Separate text::               
45 @end menu
46
47
48 @node Text scripts
49 @subsubsection Text scripts
50
51 @cindex Text scripts
52 @cindex text items, non-empty
53 @cindex non-empty texts
54 @cindex quoted text
55
56 Simple @qq{quoted text} indications may be added
57 to a score, as demonstrated in the following example.
58 Such indications may be manually placed
59 above or below the staff, using the
60 syntax described in @ref{Direction and
61 placement}.
62
63 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
64 d8^"pizz." e f g a4-"scherz." f
65 @end lilypond
66
67 This syntax is actually a shorthand; more complex text
68 formatting may be added to a note by explicitly using a
69 @code{\markup} block, as described in @ref{Formatting text}.
70
71 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
72 d8^\markup { \italic pizz. } e f g 
73 a4_\markup { \tiny scherz. \bold molto } f
74 @end lilypond
75
76 By default, text indications do not influence the note spacing.
77 However, their widths can be taken into account:
78 in the following example, the first text string does not affect 
79 spacing, whereas the second one does.
80
81 @lilypond[quote,fragment,ragged-right,verbatim,relative=1]
82 d8^"pizz." e f g
83 \textLengthOn
84 a4_"scherzando" f
85 @end lilypond
86
87 @predefined
88
89 @funindex \textLengthOn
90 @code{\textLengthOn},
91 @funindex \textLengthOff
92 @code{\textLengthOff}
93
94
95 @seealso
96
97 Notation Reference:
98 @ref{Formatting text},
99 @ref{Direction and placement}.
100
101 Snippets:
102 @rlsr{Text}.
103
104 Internals Reference:
105 @rinternals{TextScript}.
106
107 @knownissues
108
109 Checking to make sure that text scripts and lyrics are within the
110 margins is a relatively large computational task.  To speed up
111 processing, LilyPond does not perform such calculations by
112 default; to enable it, use
113
114 @example
115 \override Score.PaperColumn #'keep-inside-line = ##t
116 @end example
117
118
119 @node Text spanners
120 @subsubsection Text spanners
121
122 @cindex Text spanners
123
124 Some performance indications, e.g., @notation{rallentando} or
125 @notation{accelerando}, are written as text and are extended over
126 multiple notes with dotted lines.
127 Such objects, called @qq{spanners}, may be created
128 from one note to another using the following syntax:
129
130 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
131 \override TextSpanner #'bound-details #'left #'text = "rit." 
132 b1\startTextSpan 
133 e,\stopTextSpan
134 @end lilypond
135
136 @noindent
137 The string to be printed is set through
138 object properties.  By default it is printed in italic characters,
139 but different formatting can be obtained using
140 @code{\markup} blocks, as described in @ref{Formatting text}.
141
142 @lilypond[quote,ragged-right,fragment,relative=2,verbatim]
143 \override TextSpanner #'bound-details #'left #'text =
144   \markup { \upright "rit." } 
145 b1\startTextSpan c
146 e,\stopTextSpan
147 @end lilypond
148
149 The line style, as well as the text string, can be defined as an
150 object property.  This syntax is described in @ref{Line styles}.
151
152 @predefined
153
154 @funindex textSpannerUp
155 @code{\textSpannerUp},
156 @funindex textSpannerDown
157 @code{\textSpannerDown},
158 @funindex textSpannerNeutral
159 @code{\textSpannerNeutral}
160
161 @seealso
162
163 Notation Reference:
164 @ref{Line styles},
165 @ref{Dynamics}.
166
167 Snippets:
168 @rlsr{Text}.
169
170 Internals Reference:
171 @rinternals{TextSpanner}.
172
173
174 @node Text marks
175 @subsubsection Text marks
176
177 @cindex coda on bar line
178 @cindex segno on bar line
179 @cindex fermata on bar line
180 @cindex bar lines, symbols on
181 @funindex \mark
182
183 Various text elements may be added to a score using
184 the syntax described in @ref{Rehearsal marks}:
185
186 @c \mark needs to be placed on a separate line (it's not
187 @c attached to an object like \markup is). -vv
188
189 @lilypond[verbatim,quote,ragged-right,fragment,relative=2]
190 c4
191 \mark "Allegro"
192 c c c
193 @end lilypond
194
195 This syntax makes it possible to put any text on a bar line;
196 more complex text formatting may be added using a @code{\markup}
197 block, as described in @ref{Formatting text}:
198
199 @lilypond[fragment,quote,ragged-right,verbatim,relative=1]
200 <c e>1
201 \mark \markup { \italic { colla parte } }
202 <d f>2 <e g>
203 <c f aes>1
204 @end lilypond
205
206 @noindent
207 This syntax also allows to print special signs, like coda, segno
208 or fermata, by specifying the appropriate symbol name as explained in
209 @ref{Music notation inside markup}:
210
211 @lilypond[fragment,quote,ragged-right,verbatim,relative=1]
212 <f bes>2 <d aes'>
213 \mark \markup { \musicglyph #"scripts.ufermata" }
214 <e g>1
215 @end lilypond
216
217 @noindent
218 Such objects are only typeset above the top staff of the score; depending on
219 whether they are specified at the end or the middle of a bar, they 
220 can be placed above the bar line or between notes.  When specified at the
221 beginning of a score or at a line break, marks will be printed at
222 the beginning of the line (the next line, in case of a line break).
223
224 @lilypond[fragment,quote,ragged-right,verbatim,relative=2]
225 \mark "Allegro"
226 c1 c
227 \mark "assai" \break
228 c  c
229 @end lilypond
230
231
232 @snippets
233
234 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
235 {printing-marks-at-the-end-of-a-line-or-a-score.ly}
236
237 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
238 {aligning-marks-with-various-notation-objects.ly}
239
240 @lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
241 {printing-marks-on-every-staff.ly}
242
243 @seealso
244
245 Notation Reference:
246 @ref{Rehearsal marks},
247 @ref{Formatting text},
248 @ref{Music notation inside markup},
249 @ref{The Feta font}.
250
251 Snippets:
252 @rlsr{Text}.
253
254 Internals Reference:
255 @rinternals{RehearsalMark}.
256
257 @knownissues
258 @c  To be removed when Issue 69 in the tracker gets fixed. -vv
259
260 If a mark is entered at the end of the last bar of the score (where
261 there is no next line), then the mark will not be printed at
262 all.
263
264 @node Separate text
265 @subsubsection Separate text
266
267 @cindex separate text
268 @cindex standalone text
269 @cindex top-level text
270 @cindex text, standalone
271 @funindex \markup
272
273 A @code{\markup} block can exist by itself, outside of any
274 any @code{\score} block, as a @qq{top-level
275 expression}.  This syntax is described in @ref{File structure}.
276
277 @lilypond[verbatim,quote]
278 \markup {
279   Tomorrow, and tomorrow, and tomorrow...
280 }
281 @end lilypond
282
283 @noindent
284 This allows printing text separately
285 from the music, which is particularly 
286 useful when the input file contains
287 several music pieces, as described in
288 @ref{Multiple scores in a book}.
289
290 @lilypond[quote,ragged-right,verbatim]
291 \score {
292   c'1
293 }
294 \markup {
295   Tomorrow, and tomorrow, and tomorrow...
296 }
297 \score {
298   c'1
299 }
300 @end lilypond
301
302 Using a specific syntax, text blocks can be spread
303 over multiple pages, making it possible to print
304 text documents or books (and therefore to
305 use LilyPond as a word processor).  This syntax is described in
306 @ref{Multi-page markup}.
307
308 @predefined
309
310 @code{\markup},
311 @funindex \markuplines
312 @code{\markuplines}
313
314 @ignore
315 @snippets
316
317 TODO: add convenient snippets in input/new -vv
318 @end ignore
319
320 @seealso
321
322 Notation Reference: @ref{Formatting text},
323 @ref{File structure}, 
324 @ref{Multiple scores in a book},
325 @ref{Multi-page markup}.
326
327 Snippets:
328 @rlsr{Text}.
329
330 Internals Reference: @rinternals{TextScript}.
331
332
333 @node Formatting text
334 @subsection Formatting text
335
336 This section presents basic and advanced text formatting,
337 using the @code{\markup} mode specific syntax.
338
339 @menu
340 * Text markup introduction::    
341 * Selecting font and font size::      
342 * Text alignment::              
343 * Graphic notation inside markup::  
344 * Music notation inside markup::  
345 * Multi-page markup::          
346 @end menu
347
348 @node Text markup introduction
349 @subsubsection Text markup introduction
350
351 @cindex markup
352 @cindex text markup
353 @cindex markup text
354 @cindex typeset text
355 @funindex \markup
356
357 A @code{\markup} block is used to typeset text with an extensible
358 specific syntax called @qq{markup mode}.
359
360 @cindex markup expressions
361 @cindex markup syntax
362
363 The markup syntax is similar to LilyPond's usual syntax: a
364 @code{\markup} expression is enclosed in curly braces @code{@{
365 @dots{} @}}.  A single word is regarded as a minimal expression,
366 and therefore does not need to be enclosed with braces.
367
368 Unlike simple @qq{quoted text} indications, @code{\markup} blocks
369 may contain nested expressions or specific commands,
370 entered using the backslash @code{\} character.
371 Such commands only affect the first following expression.
372
373 @lilypond[quote,verbatim,fragment,relative=1]
374 e1-\markup intenso
375 a2^\markup { poco \italic più forte  }
376 c e1
377 d2_\markup { \italic "string. assai" }
378
379 b1^\markup { \bold { molto \italic  agitato } }
380 c
381 @end lilypond
382
383 @cindex special characters in markup mode
384 @cindex markup mode, special characters
385 @cindex reserved characters, printing
386 @cindex printing special characters
387 @cindex quoted text in markup mode
388
389 A @code{\markup} block may also contain quoted text strings.
390 Such strings are treated as minimal text expressions, and
391 therefore any markup command or special character (such as
392 @code{\} and @code{#}) will be printed verbatim without affecting
393 the formatting of the text.  This syntax even allows to print
394 double quotation marks, by preceding them with backslashes
395
396 @lilypond[quote,verbatim,fragment,relative=1]
397 d1^"\italic markup..."
398 d_\markup \italic "... prints \"italic\" letters!"
399 d d
400 @end lilypond
401
402 The way markup expressions are defined affects 
403 how these expressions will be stacked, centered and aligned
404 when using the commands explained in @ref{Text alignment}.
405
406 @lilypond[quote,verbatim,fragment,relative=1]
407 c1^\markup { \column { a bbbb \line { c d } } }
408 c1^\markup { \center-column { a bbbb c } }
409 c1^\markup { \line { a b c } }
410 @end lilypond
411
412 Lists of words that are not enclosed with double quotes
413 or preceded by a command are not treated as a distinct
414 expression.  In the following example, the first two
415 @code{\markup} expressions are equivalent:
416
417 @lilypond[quote,verbatim,fragment,relative=1]
418 c1^\markup { \center-column { a bbb c } }
419 c1^\markup { \center-column { a { bbb c } } }
420 c1^\markup { \center-column { a \line { bbb c } } }
421 @end lilypond
422
423
424 Markups can be stored in variables.  Such variables may be
425 directly attached to notes:
426
427 @lilypond[quote,verbatim]
428 allegro = \markup { \bold \large Allegro }
429
430 {
431   d''8.^\allegro
432   d'16 d'4 r2
433 }
434 @end lilypond
435
436
437 @noindent
438 An exhaustive list of @code{\markup}-specific commands can be found in
439 @ref{Text markup commands}.
440
441
442 @seealso
443
444 Notation Reference:
445 @ref{Text markup commands}.
446
447 Snippets:
448 @rlsr{Text}.
449
450 Internals Reference:
451 @rinternals{TextScript}.
452
453 Installed files:
454 @file{scm/@/markup@/.scm}.
455
456
457 @knownissues
458
459 Syntax errors for markup mode can be confusing.
460
461
462 @node Selecting font and font size
463 @subsubsection Selecting font and font size
464
465 @cindex font switching
466 @funindex \italic
467 @funindex \bold
468 @funindex \underline
469
470 Basic font switching is supported in markup mode:
471
472 @lilypond[quote,verbatim,relative=2]
473 {
474   d1^\markup { 
475     \bold { Più mosso } 
476     \italic { non troppo \underline Vivo } 
477   }
478   r2 r4 r8
479   d,_\markup { \italic quasi \smallCaps Tromba }
480   f1 d2 r
481 }
482 @end lilypond
483
484 @cindex font size
485 @cindex text size
486 @funindex \fontsize
487 @funindex \smaller
488 @funindex \larger
489 @funindex \bigger
490 @funindex \magnify
491
492 The size of the characters can also be altered in different ways:
493 @itemize
494 @item
495 the font size can be defined to an absolute value,
496
497 @item
498 predefined commands allow to easily select standard sizes,
499
500 @item
501 the font size can also be changed relatively to its previous value.
502 @end itemize
503
504 @noindent
505 The following example demonstrates these three methods:
506
507 @lilypond[quote,verbatim,relative=2]
508 {
509   f1^\markup { \fontsize #5 Sinfonia } 
510   a,_\markup { 
511     \tiny espressivo
512     \large e
513     \normalsize intenso 
514   }
515   bes^\markup { (con 
516     \larger grande 
517     \smaller emozione 
518     \magnify #0.6 { e sentimento } )
519   }
520   d c2 r8 c bes a g1
521 }
522 @end lilypond
523
524 @cindex subscript
525 @cindex superscript
526 @funindex \super
527 @funindex \sub
528
529 Text may be printed as subscript or superscript. By default
530 these are printed in a smaller size, but a normal size can be used as well:
531
532 @lilypond[quote,verbatim]
533 \markup {
534   \column {
535     \line { 1 \super st movement }
536     \line { 1 \normal-size-super st movement 
537       \sub { (part two) }  }
538   }
539 }
540 @end lilypond
541
542 @cindex font families
543
544 The markup mode provides an easy way to select alternate
545 font families.  The default serif font, of roman type, is
546 automatically selected unless specified otherwise: on the
547 last line of the following example, there is no difference
548 between the first and the second word.
549
550 @lilypond[quote,verbatim]
551 \markup {
552   \column {
553     \line { Act \number 1 }
554     \line { \sans { Scene I. } }
555     \line { \typewriter { Verona. An open place. } }
556     \line { Enter \roman Valentine and Proteus. }
557   }
558 }
559 @end lilypond
560
561 @noindent
562 Some of these font families, used for specific items
563 such as numbers or dynamics, do not provide all
564 characters, as mentioned in @ref{New dynamic marks} and
565 @ref{Manual repeat marks}.
566
567 @c \concat is actually documented in Align (it is not
568 @c a font-switching command). But we need it here. -vv
569
570 When used inside a word, some font-switching or formatting
571 commands may produce an unwanted blank space.  This can
572 easily be solved by concatenating the text elements together:
573
574 @lilypond[quote,verbatim]
575 \markup {
576   \column {
577     \line {
578       \concat { 1 \super st }
579       movement
580     }
581     \line {
582       \concat { \dynamic p , }
583       \italic { con dolce espressione }
584     }
585   }
586 }
587 @end lilypond
588
589 An exhaustive list of font-switching, font-size
590 and font-families related commands can be found in @ref{Font}.
591
592 Defining custom font sets is also possible, as explained in
593 @ref{Fonts}.
594
595 @predefined
596
597 @funindex \teeny
598 @funindex \tiny
599 @funindex \small
600 @funindex \normalsize
601 @funindex \large
602 @funindex \huge
603 @code{\teeny},
604 @code{\tiny},
605 @code{\small},
606 @code{\normalsize},
607 @code{\large},
608 @code{\huge}.
609
610 @seealso
611 Notation Reference:
612 @ref{Font},
613 @ref{New dynamic marks},
614 @ref{Manual repeat marks},
615 @ref{Fonts}.
616
617 Snippets:
618 @rlsr{Text}.
619
620 Internals Reference:
621 @rinternals{TextScript}.
622
623 Installed files:
624 @file{scm/@/define@/-markup@/-commands@/.scm}.
625
626
627 @node Text alignment
628 @subsubsection Text alignment
629
630 @cindex text, aligning
631 @cindex aligning text
632
633 This subsection discusses how to place text in markup mode,
634 inside a @code{\markup} block.  Markup objects can also
635 be moved as a whole, using the syntax described in
636 @rlearning{Moving objects}.
637
638 @c Padding commands should be mentioned on this page, but
639 @c most of these require \box to be more clearly illustrated. -vv
640
641 @cindex text, horizontal alignment
642 @cindex horizontal text alignment
643 @funindex \left-align
644 @funindex \center-align
645 @funindex \right-align
646
647 Markup objects may be aligned in different ways.  By default,
648 a text indication is aligned on its left edge: in the following
649 example, there is no difference
650 between the first and the second markup.
651
652 @lilypond[quote,verbatim,fragment,relative=1]
653 a1-\markup { poco }
654 e'
655 a,-\markup { \left-align poco }
656 e'
657 a,-\markup { \center-align { poco } }
658 e'
659 a,-\markup { \right-align poco }
660 @end lilypond
661
662 @funindex \halign
663
664 Horizontal alignment may be fine-tuned
665 using a numeric value:
666
667 @lilypond[quote,verbatim,fragment,relative=1]
668 a1-\markup { \halign #-1 poco }
669 e'
670 a,-\markup { \halign #0 poco }
671 e'
672 a,-\markup { \halign #0.5 poco }
673 e'
674 a,-\markup { \halign #2 poco }
675 @end lilypond
676
677 @noindent
678 Some objects may have alignment procedures of their own,
679 and therefore are not affected by these commands.  It is
680 possible to move such markup objects as a whole, as shown
681 for instance in @ref{Text marks},
682
683 @cindex text, vertical alignment
684 @cindex vertical text alignment
685 @funindex \raise
686 @funindex \lower
687
688 Vertical alignment is a bit more complex.  As stated above,
689 markup objects can be moved as a whole; however, it is also
690 possible to move specific elements inside a markup block.
691 In this case, the element to be moved needs to be preceded
692 with an @emph{anchor point}, that can be another markup element
693 or an invisible object.  The following example demonstrates these
694 two possibilities; the last markup in this example has no anchor
695 point, and therefore is not moved.
696
697 @lilypond[quote,verbatim,fragment,relative=1]
698 d2^\markup { 
699   Acte I
700   \raise #2 { Scène 1 }
701 }
702 a'
703 g_\markup {
704   \null
705   \lower #4 \bold { Très modéré }
706 }
707 a
708 d,^\markup {
709   \raise #4 \italic { Une forêt. }
710 }
711 a'4 a g2 a
712 @end lilypond
713
714 @funindex \general-align
715 @funindex \translate
716 @funindex \translate-scaled
717
718 Some commands can affect both the horizontal and vertical
719 alignment of text objects in markup mode.  Any object
720 affected by these commands must be preceded with an
721 anchor point:
722
723 @lilypond[quote,verbatim,fragment,relative=1]
724 d2^\markup {
725   Acte I
726   \translate #'(-1 . 2) "Scène 1"
727 }
728 a'
729 g_\markup {
730   \null
731   \general-align #Y #3.2 \bold "Très modéré"
732 }
733 a
734 d,^\markup {
735   \null
736   \translate-scaled #'(-1 . 2) \teeny "Une forêt."
737 }
738 a'4 a g2 a
739 @end lilypond
740
741 @funindex \column
742 @funindex \center-column
743
744 @cindex multi-line markup
745 @cindex multi-line text
746 @cindex columns, text
747
748 A markup object may include several lines of text.
749 In the following example, each element or expression
750 is placed on its own line, either left-aligned or centered:
751
752 @lilypond[quote,verbatim]
753 \markup {
754   \column {
755     a
756     "b c"
757     \line { d e f }
758   }
759   \hspace #10
760   \center-column {
761     a
762     "b c"
763     \line { d e f }
764   }
765 }
766 @end lilypond
767
768 @funindex \fill-line
769
770 @cindex centering text on the page
771
772 Similarly, a list of elements or expressions may be
773 spread to fill the entire horizontal line width (if there
774 is only one element, it will be centered on the page).
775 These expressions can, in turn, include multi-line text
776 or any other markup expression:
777
778 @lilypond[quote,verbatim]
779 \markup {
780   \fill-line {
781     \line { William S. Gilbert }
782     \center-column {
783       \huge \smallCaps "The Mikado"
784       or
785       \smallCaps "The Town of Titipu"
786     }
787     \line { Sir Arthur Sullivan }
788   }
789 }
790 \markup {
791   \fill-line { 1885 } 
792 }
793 @end lilypond
794
795 @funindex \wordwrap
796 @funindex \justify
797
798 @cindex wordwrapped text
799 @cindex justified text
800
801 Long text indications can also be automatically wrapped
802 accordingly to the given line width.  These will be
803 either left-aligned or justified, as shown in
804 the following example.
805
806 @lilypond[quote,verbatim]
807 \markup {
808   \column {
809     \line  \smallCaps { La vida breve }
810     \line \bold { Acto I }
811     \wordwrap \italic {
812       (La escena representa el corral de una casa de
813       gitanos en el Albaicín de Granada. Al fondo una
814       puerta por la que se vé el negro interior de
815       una Fragua, iluminado por los rojos resplandores
816       del fuego.) 
817     }
818     \hspace #0
819
820     \line \bold { Acto II }
821     \override #'(line-width . 50)
822     \justify \italic {
823       (Calle de Granada. Fachada de la casa de Carmela
824       y su hermano Manuel con grandes ventanas abiertas
825       a través de las que se ve el patio
826       donde se celebra una alegre fiesta)
827     }
828   }
829 }
830 @end lilypond
831
832 An exhaustive list of text alignment commands
833 can be found in @ref{Align}.
834
835 @seealso
836 Learning Manual:
837 @rlearning{Moving objects}.
838
839 Notation Reference:
840 @ref{Align},
841 @ref{Text marks}.
842
843 Snippets:
844 @rlsr{Text}.
845
846 Internals Reference: @rinternals{TextScript}.
847
848 Installed files:
849 @file{scm/@/define@/-markup@/-commands@/.scm}.
850
851
852 @node Graphic notation inside markup
853 @subsubsection Graphic notation inside markup
854
855 @cindex graphics, embedding
856 @cindex drawing graphic objects
857
858 Various graphic objects may be added to a score,
859 using specific markup commands.
860
861 @funindex \box
862 @funindex \circle
863 @funindex \rounded-box
864 @funindex \bracket
865 @funindex \hbracket
866
867 @cindex decorating text
868 @cindex framing text
869
870 Some markup commands allow to decorate text elements
871 with graphics, as demonstrated in the following example.
872
873 @lilypond[quote,verbatim]
874 \markup \fill-line {
875   \center-column {
876     \circle Jack
877     \box "in the box"
878     \null
879     \line {
880       Erik Satie
881       \hspace #3
882       \bracket "1866 - 1925"
883     }
884     \null
885     \rounded-box \bold Prelude
886   }
887 }
888 @end lilypond
889
890 @funindex \pad-markup
891 @funindex \pad-x
892 @funindex \pad-to-box
893 @funindex \pad-around
894
895 @cindex padding around text
896 @cindex text padding
897
898 Some commands may require to increase the padding around
899 the text: this is achieved with some specific commands
900 exhaustively described in @ref{Align}.
901
902 @lilypond[quote,verbatim]
903 \markup \fill-line {
904   \center-column {
905     \box "Charles Ives (1874 - 1954)"
906     \null
907     \box \pad-markup #2 "THE UNANSWERED QUESTION"
908     \box \pad-x #8 "A Cosmic Landscape"
909     \null
910   }
911 }
912 \markup \column {
913   \line {
914     \hspace #10
915     \box \pad-to-box #'(-5 . 20) #'(0 . 5)
916       \bold "Largo to Presto"
917   }
918   \pad-around #3
919       "String quartet keeps very even time,
920 Flute quartet keeps very uneven time."
921 }
922 @end lilypond
923
924 @funindex \combine
925 @funindex \draw-circle
926 @funindex \filled-box
927 @funindex \triangle
928 @funindex \draw-line
929 @funindex \arrow-head
930
931 @cindex graphic notation
932 @cindex symbols, non-musical
933
934 Other graphic elements or symbols may be printed
935 without requiring any text.  As with any markup
936 expression, such objects can be combined together:
937
938 @lilypond[quote,verbatim]
939 \markup {
940   \combine
941     \draw-circle #4 #0.4 ##f
942     \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
943   \hspace #5
944
945   \center-column {
946     \triangle ##t
947     \combine
948       \draw-line #'(0 . 4)
949       \arrow-head #Y #DOWN ##f
950   }
951 }
952 @end lilypond
953
954 @funindex \epsfile
955 @funindex \postscript
956
957 @cindex embedded graphics
958 @cindex images, embedding
959 @cindex graphics, embedding
960 @cindex postscript
961
962 Advanced graphic features include the ability to
963 include external image files converted to the
964 Encapsulated PostScript format (@emph{eps}), or
965 to directly embed graphics into the input file,
966 using native PostScript code.  In such a case, it
967 may be useful to explicitely specify the size of the
968 drawing, as demonstrated below:
969
970 @lilypond[quote,verbatim,fragment,relative=1]
971 c1^\markup {
972   \combine
973     \epsfile #X #10 #"./Documents/git/Documentation/user/context-example.eps"
974     \with-dimensions #'(0 . 6) #'(0 . 10)
975     \postscript #"
976       -2 3 translate
977       2.7 2 scale
978       newpath
979       2 -1 moveto
980       4 -2 4 1 1 arct
981       4 2 3 3 1 arct
982       0 4 0 3 1 arct
983       0 0 1 -1 1 arct
984       closepath
985       stroke"
986   }
987 c
988 @end lilypond
989
990 An exhaustive list of graphics-specific commands
991 can be found in @ref{Graphic}.
992
993 @seealso
994 Notation Reference:
995 @ref{Graphic},
996 @ref{Editorial annotations}.
997
998 Snippets:
999 @rlsr{Text}.
1000
1001 Internals Reference: @rinternals{TextScript}.
1002
1003 Installed files:
1004 @file{scm/@/define@/-markup@/-commands@/.scm},
1005 @file{scm/@/stencil@/.scm}.
1006
1007 @node Music notation inside markup
1008 @subsubsection Music notation inside markup
1009
1010 Various musical notation elements may be added
1011 to a score, inside a markup object.
1012
1013 Notes and accidentals can be entered using specific
1014 commands:
1015
1016 @lilypond[quote,verbatim,fragment,relative=2]
1017 a2 a^\markup {
1018   \note #"4" #1
1019   =
1020   \note-by-number #1 #1 #1.5
1021 }
1022 b1_\markup {
1023   \natural \semiflat \flat
1024   \sesquiflat \doubleflat
1025 }
1026 \glissando
1027 a1_\markup {
1028   \natural \semisharp \sharp
1029   \sesquisharp \doublesharp
1030 }
1031 \glissando b
1032 @end lilypond
1033
1034 Other notation objects may also be printed
1035 in markup mode:
1036
1037 @lilypond[quote,verbatim,fragment,relative=1]
1038 g1 bes
1039 ees-\markup {
1040   \finger 4
1041   \tied-lyric #"~"
1042   \finger 1
1043 }
1044 fis_\markup { \dynamic rf }
1045 bes^\markup {
1046   \beam #8 #0.1 #0.5
1047 }
1048 cis
1049 d-\markup {
1050   \markalphabet #8
1051   \markletter #8
1052 }
1053 @end lilypond 
1054
1055 More generally, any available musical symbol may be
1056 included separately in a markup object, as demonstrated
1057 below; an exhaustive list of these symbols and their
1058 names can be found in @ref{The Feta font}.
1059
1060 @lilypond[quote,verbatim,fragment,relative=2]
1061 c2
1062 c'^\markup { \musicglyph #"eight" }
1063 c,4
1064 c,8._\markup { \musicglyph #"clefs.G_change" }
1065 c16
1066 c2^\markup { \musicglyph #"timesig.neomensural94" }
1067 @end lilypond
1068 @c TODO: add \lookup here? -vv
1069
1070 @noindent
1071 Another way of printing non-text glyphs is described
1072 in @ref{Fonts explained}.
1073
1074 The markup mode also supports diagrams for specific
1075 instruments:
1076
1077 @lilypond[quote,verbatim,fragment,relative=2]
1078 c1^\markup {
1079   \fret-diagram-terse #"x;x;o;2;3;2;"
1080 }
1081 c^\markup {
1082   \harp-pedal #"^-v|--ov^"
1083 }
1084 c
1085 c^\markup {
1086   \combine
1087     \musicglyph #"accordion.accDiscant"
1088     \combine
1089       \raise #0.5 \musicglyph #"accordion.accDot"
1090       \raise #1.5 \musicglyph #"accordion.accDot"
1091 }
1092 @end lilypond
1093
1094 @c The accordion diagram is actually taken from a snippet.
1095
1096 @noindent
1097 Such diagrams are documented in @ref{Instrument Specific Markup}.
1098
1099 A whole score can even be nested inside a markup object.
1100 In such a case, the nested @code{\score} block must
1101 contain a @code{\layout} block, as demonstrated here:
1102
1103 @lilypond[quote,verbatim,fragment,relative=1]
1104 c4 d^\markup {
1105   \score {
1106     \relative { c4 d e f }
1107     \layout { }
1108   }
1109 }
1110 e f |
1111 c d e f
1112 @end lilypond
1113
1114 An exhaustive list of music notation related commands can be
1115 found in @ref{Music}.
1116
1117 @seealso
1118 Notation Reference:
1119 @ref{Music},
1120 @ref{The Feta font},
1121 @ref{Fonts explained}.
1122
1123 Snippets:
1124 @rlsr{Text}.
1125
1126 Internals Reference: @rinternals{TextScript}.
1127
1128 Installed files:
1129 @file{scm/@/define@/-markup@/-commands@/.scm},
1130 @file{scm/@/fret@/-diagrams@/.scm},
1131 @file{scm/@/harp@/-pedals@/.scm}.
1132
1133 @node Multi-page markup
1134 @subsubsection Multi-page markup
1135
1136 Although standard markup objects are not breakable, a
1137 specific syntax allows to enter lines of text that can
1138 spread over multiple pages:
1139
1140 @lilypond[quote,verbatim]
1141 \markuplines {
1142   \justified-lines {
1143     A very long text of justified lines.
1144     ...
1145   }
1146   \wordwrap-lines {
1147     An other very long paragraph.
1148     ...
1149   }
1150   ...
1151 }
1152 @end lilypond
1153
1154 This specific syntax accepts a list of markups, that can be
1155 @itemize
1156 @item
1157 the result of a markup list command,
1158 @item
1159 a list of markups,
1160 @item
1161 a list of markup lists.
1162 @end itemize
1163
1164 An exhaustive list of markup list commands can be found in
1165 @ref{Text markup list commands}.
1166
1167 @seealso
1168 Notation Reference:
1169 @ref{Text markup list commands},
1170 @ref{New markup list command definition}.
1171
1172 Snippets:
1173 @rlsr{Text}.
1174
1175 Internals Reference: @rinternals{TextScript}.
1176
1177 Installed files:
1178 @file{scm/@/define@/-markup@/-commands@/.scm}.
1179
1180 @predefined
1181 @funindex \markuplines
1182 @code{\markuplines}
1183
1184
1185 @node Fonts
1186 @subsection Fonts
1187
1188 This section presents the way fonts are handled,
1189 and how they may be changed in scores.
1190
1191 @menu
1192 * Fonts explained::
1193 * Single entry fonts::
1194 * Entire document fonts::
1195 @end menu
1196
1197 @node Fonts explained
1198 @subsubsection Fonts explained
1199
1200 @cindex Pango
1201 @cindex fonts, explained
1202 @funindex font-interface
1203
1204 Fonts are handled through several libraries.
1205 FontConfig is used to detect available fonts on the system;
1206 the selected fonts are rendered using Pango.
1207
1208 Music notation fonts can be described as a set of
1209 specific glyphs, ordered in several families.
1210 The following syntax allows to directly use various
1211 LilyPond @code{feta} non-text fonts in markup mode:
1212
1213 @lilypond[quote,verbatim,fragment,relative=2]
1214 a1^\markup {
1215   \vcenter {
1216     \override #'(font-encoding . fetaBraces)
1217     \lookup #"brace120"
1218     \override #'(font-encoding . fetaNumber)
1219     \column { 1 3 }
1220     \override #'(font-encoding . fetaDynamic)
1221     sf
1222     \override #'(font-encoding . fetaMusic)
1223     \lookup #"noteheads.s0petrucci"
1224   }
1225 }
1226 @end lilypond
1227
1228 @noindent
1229 A simpler, but more limited syntax is also described in
1230 @ref{Music notation inside markup}.
1231
1232 Three families of text fonts are made available: the
1233 @emph{roman} (serif) font, that defaults to New Century
1234 Schoolbook, the @emph{sans} font and the monospaced
1235 @emph{typewriter} font -- these last two families are
1236 determined by the Pango installation.
1237
1238 Each family may include different shapes and series.
1239 The following example demonstrates the ability to select
1240 alternate families, shapes, series and sizes:
1241
1242 @lilypond[quote,verbatim,fragment,relative=2]
1243   \override Score.RehearsalMark #'font-family = #'typewriter
1244   \mark \markup "Ouverture"
1245   \key d \major
1246   \override  Voice.TextScript #'font-shape = #'italic
1247   \override  Voice.TextScript #'font-series = #'bold
1248   d''2.^\markup "Allegro"
1249   r4
1250 @end lilypond
1251
1252 @noindent
1253 A similar syntax may be used in markup mode, however in this case
1254 it is preferable to use the simpler syntax explained in
1255 @ref{Selecting font and font size}:
1256
1257 @lilypond[quote,verbatim]
1258 \markup {
1259   \column {
1260     \line {
1261       \override #'(font-shape . italic)
1262       \override #'(font-size . 4)
1263       Idomeneo,
1264     }
1265     \line {
1266       \override #'(font-family . typewriter)
1267       {
1268         \override #'(font-series . bold)
1269         re
1270         di
1271       }
1272       \override #'(font-family . sans)
1273       Creta
1274     }
1275   }
1276 }
1277 @end lilypond
1278
1279 @ignore
1280 @c FIXME: This needs an example -vv
1281
1282 The size of the font may be set with the @code{font-size}
1283 property.  The resulting size is taken relative to the
1284 @code{text-font-size} as defined in the @code{\paper} block.
1285 @end ignore
1286
1287 Although it is easy to switch between preconfigured fonts,
1288 it is also possible to use other fonts, as explained in the
1289 following sections: @ref{Single entry fonts} and
1290 @ref{Entire document fonts}.
1291
1292 @seealso
1293 Notation Reference:
1294 @ref{The Feta font},
1295 @ref{Music notation inside markup},
1296 @ref{Selecting font and font size},
1297 @ref{Font}.
1298
1299 @node Single entry fonts
1300 @subsubsection Single entry fonts
1301
1302 Any font that is installed on the operating system and recognized
1303 by FontConfig may be used in a score, using the following syntax:
1304
1305 @lilypond[quote,verbatim,fragment,relative=1]
1306 \override Staff.TimeSignature #'font-name = #"Charter"
1307 \override Staff.TimeSignature #'font-size = #2
1308 \time 3/4
1309
1310 c1_\markup {
1311   \override #'(font-name . "Vera Bold")
1312     { Vera Bold }
1313 }
1314 @end lilypond
1315
1316 @funindex show-available-fonts
1317
1318 The following command displays a list of all available fonts
1319 on the operating system:
1320
1321 @example
1322 lilypond -dshow-available-fonts x
1323 @end example
1324
1325 @noindent
1326 The last argument of the command can be anything, but has to be
1327 present.
1328
1329 @seealso
1330 Notation Reference:
1331 @ref{Fonts explained},
1332 @ref{Entire document fonts}.
1333
1334 Snippets:
1335 @rlsr{Text}.
1336
1337 Installed files:
1338 @file{lily/@/font@/-config@/-scheme@/.cc}.
1339
1340 @node Entire document fonts
1341 @subsubsection Entire document fonts
1342
1343
1344 It is possible to change the default font families for the
1345 entire document.  In such a case, the following syntax has
1346 to be used, by providing three font families that will be
1347 respectively used as @emph{roman}, @emph{sans} and @emph{typewriter}
1348 fonts, as explained in @ref{Fonts explained}.
1349
1350 @cindex font families, setting
1351 @funindex make-pango-font-tree
1352
1353 @lilypond[verbatim,quote]
1354 \paper  {
1355   myStaffSize = #20
1356   #(define fonts
1357     (make-pango-font-tree "Times New Roman"
1358                           "Nimbus Sans"
1359                           "Luxi Mono"
1360                            (/ myStaffSize 20)))
1361 }
1362
1363 \relative c'{
1364   c1-\markup {
1365     roman,
1366     \sans sans,
1367     \typewriter typewriter. }
1368 }
1369 @end lilypond
1370
1371 @c we don't do Helvetica / Courier, since GS incorrectly loads
1372 @c Apple TTF fonts
1373
1374 @seealso
1375 Notation Reference:
1376 @ref{Fonts explained},
1377 @ref{Single entry fonts},
1378 @ref{Selecting font and font size},
1379 @ref{Font}.
1380