LilyPond Notation Reference: 1.8.2 Formatting text

### 1.8.2 Formatting text

This section presents basic and advanced text formatting, using the `\markup` mode specific syntax.

#### Text markup introduction

A `\markup` block is used to typeset text with an extensible syntax called “markup mode”.

The markup syntax is similar to LilyPond’s usual syntax: a `\markup` expression is enclosed in curly braces `{… }`. A single word is regarded as a minimal expression, and therefore does not need to be enclosed with braces.

Unlike simple “quoted text” indications, `\markup` blocks may contain nested expressions or markup commands, entered using the backslash `\` character. Such commands only affect the first following expression.

>     a1-\markup intenso
>     a2^\markup { poco \italic più forte  }
>     c e1
>     d2_\markup { \italic "string. assai" }
>     e
>     b1^\markup { \bold { molto \italic  agitato } }
>     c

A `\markup` block may also contain quoted text strings. Such strings are treated as minimal text expressions, and therefore any markup command or special character (such as `\` and `#`) will be printed verbatim without affecting the formatting of the text. Double quotation marks themselves may be printed by preceding them with backslashes.

>     a1^"\italic markup..."
>     a_\markup { \italic "... prints \"italic\" letters!" }
>     a a

To be treated as a distinct expression, a list of words needs to be enclosed with double quotes or preceded by a command. The way markup expressions are defined affects how these expressions will be stacked, centered and aligned; in the following example, the second `\markup` expression is treated the same as the first one:

>     c1^\markup { \center-column { a bbb c } }
>     c1^\markup { \center-column { a { bbb c } } }
>     c1^\markup { \center-column { a \line { bbb c } } }
>     c1^\markup { \center-column { a "bbb c" } }

Markups can be stored in variables. Such variables may be directly attached to notes:

>     allegro = \markup { \bold \large Allegro }

>     {
>       d''8.^\allegro
>       d'16 d'4 r2
>     }

An exhaustive list of `\markup`-specific commands can be found in Text markup commands.

#### See also

Notation Reference: Text markup commands.

Snippets: Text.

Installed Files: ‘`scm/markup.scm`’.

#### Known issues and warnings

Syntax errors for markup mode can be confusing.

#### Selecting font and font size

Basic font switching is supported in markup mode:

>     d1^\markup {
>       \bold { Più mosso }
>       \italic { non troppo \underline Vivo }
>     }
>     r2 r4 r8
>     d,_\markup { \italic quasi \smallCaps Tromba }
>     f1 d2 r

The size of the characters can also be altered in different ways:

- the font size can be set to predefined standard sizes,
- the font size can be set to an absolute value,
- the font size can also be changed relatively to its previous value.

The following example demonstrates these three methods:

>     f1_\markup {
>       \tiny espressivo
>       \large e
>       \normalsize intenso
>     }
>     a^\markup {
>       \fontsize #5 Sinfonia
>       \fontsize #2 da
>       \fontsize #3 camera
>     }
>     bes^\markup { (con
>       \larger grande
>       \smaller emozione
>       \magnify #0.6 { e sentimento } )
>     }
>     d c2 r8 c bes a g1

Text may be printed as subscript or superscript. By default these are printed in a smaller size, but a normal size can be used as well:

>     \markup {
>       \column {
>         \line { 1 \super st movement }
>         \line { 1 \normal-size-super st movement
>           \sub { (part two) }  }
>       }
>     }

The markup mode provides an easy way to select alternate font families. The default serif font, of roman type, is automatically selected unless specified otherwise; on the last line of the following example, there is no difference between the first and the second word.

>     \markup {
>       \column {
>         \line { Act \number 1 }
>         \line { \sans { Scene I. } }
>         \line { \typewriter { Verona. An open place. } }
>         \line { Enter \roman Valentine and Proteus. }
>       }
>     }

Some of these font families, used for specific items such as numbers or dynamics, do not provide all characters, as mentioned in New dynamic marks and Manual repeat marks.

When used inside a word, some font-switching or formatting commands may produce an unwanted blank space. This can easily be solved by concatenating the text elements together:

>     \markup {
>       \column {
>         \line {
>           \concat { 1 \super st }
>           movement
>         }
>         \line {
>           \concat { \dynamic p , }
>           \italic { con dolce espressione }
>         }
>       }
>     }

An exhaustive list of font switching commands and custom font usage commands can be found in Font.

Defining custom font sets is also possible, as explained in Fonts.

#### Predefined commands

`\teeny`, `\tiny`, `\small`, `\normalsize`, `\large`, `\huge`, `\smaller`, `\larger`.

#### See also

Notation Reference: Font, New dynamic marks, Manual repeat marks, Fonts.

Snippets: Text.

Internals Reference: TextScript.

Installed Files: ‘`scm/define-markup-commands.scm`’.

#### Known issues and warnings

Using the font sizing commands `\teeny`, `\tiny`, `\small`, `\normalsize`, `\large`, and `\huge` will lead to inconsistent line spacing compared to using `\fontsize`.

#### Text alignment

This subsection discusses how to place text in markup mode. Markup objects can also be moved as a whole, using the syntax described in Moving objects.

Markup objects may be aligned in different ways. By default, a text indication is aligned on its left edge: in the following example, there is no difference between the first and the second markup.

>     d1-\markup { poco }
>     f
>     d-\markup { \left-align poco }
>     f
>     d-\markup { \center-align { poco } }
>     f
>     d-\markup { \right-align poco }

Horizontal alignment may be fine-tuned using a numeric value:

>     a1-\markup { \halign #-1 poco }
>     e'
>     a,-\markup { \halign #0 poco }
>     e'
>     a,-\markup { \halign #0.5 poco }
>     e'
>     a,-\markup { \halign #2 poco }

Some objects may have alignment procedures of their own, and therefore are not affected by these commands. It is possible to move such markup objects as a whole, as shown for instance in Text marks.

Vertical alignment is a bit more complex. As stated above, markup objects can be moved as a whole; however, it is also possible to move specific elements inside a markup block. In this case, the element to be moved needs to be preceded with an anchor point, that can be another markup element or an invisible object. The following example demonstrates these two possibilities; the last markup in this example has no anchor point, and therefore is not moved.

>     d2^\markup {
>       Acte I
>       \raise #2 { Scène 1 }
>     }
>     a'
>     g_\markup {
>       \null
>       \lower #4 \bold { Très modéré }
>     }
>     a
>     d,^\markup {
>       \raise #4 \italic { Une forêt. }
>     }
>     a'4 a g2 a

Some commands can affect both the horizontal and vertical alignment of text objects in markup mode. Any object affected by these commands must be preceded with an anchor point:

>     d2^\markup {
>       Acte I
>       \translate #'(-1 . 2) "Scène 1"
>     }
>     a'
>     g_\markup {
>       \null
>       \general-align #Y #3.2 \bold "Très modéré"
>     }
>     a
>     d,^\markup {
>       \null
>       \translate-scaled #'(-1 . 2) \teeny "Une forêt."
>     }
>     a'4 a g2 a

A markup object may include several lines of text. In the following example, each element or expression is placed on its own line, either left-aligned or centered:

>     \markup {
>       \column {
>         a
>         "b c"
>         \line { d e f }
>       }
>       \hspace #10
>       \center-column {
>         a
>         "b c"
>         \line { d e f }
>       }
>     }

Similarly, a list of elements or expressions may be spread to fill the entire horizontal line width (if there is only one element, it will be centered on the page). These expressions can, in turn, include multi-line text or any other markup expression:

>     \markup {
>       \fill-line {
>         \line { William S. Gilbert }
>         \center-column {
>           \huge \smallCaps "The Mikado"
>           or
>           \smallCaps "The Town of Titipu"
>         }
>         \line { Sir Arthur Sullivan }
>       }
>     }
>     \markup {
>       \fill-line { 1885 }
>     }

Long text indications can also be automatically wrapped accordingly to the given line width. These will be either left-aligned or justified, as shown in the following example.

>     \markup {
>       \column {
>         \line  \smallCaps { La vida breve }
>         \line \bold { Acto I }
>         \wordwrap \italic {
>           (La escena representa el corral de una casa de
>           gitanos en el Albaicín de Granada.  Al fondo una
>           puerta por la que se ve el negro interior de
>           una Fragua, iluminado por los rojos resplandores
>           del fuego.)
>         }
>         \hspace #0

>         \line \bold { Acto II }
>         \override #'(line-width . 50)
>         \justify \italic {
>           (Calle de Granada.  Fachada de la casa de Carmela
>           y su hermano Manuel con grandes ventanas abiertas
>           a través de las que se ve el patio
>           donde se celebra una alegre fiesta)
>         }
>       }
>     }

An exhaustive list of text alignment commands can be found in Align.

#### See also

Learning Manual: Moving objects.

Notation Reference: Align, Text marks.

Snippets: Text.

Internals Reference: TextScript.

Installed Files: ‘`scm/define-markup-commands.scm`’.

#### Graphic notation inside markup

Various graphic objects may be added to a score, using markup commands.

Some markup commands allow decoration of text elements with graphics, as demonstrated in the following example.

>     \markup \fill-line {
>       \center-column {
>         \circle Jack
>         \box "in the box"
>         \null
>         \line {
>           Erik Satie
>           \hspace #3
>           \bracket "1866 - 1925"
>         }
>         \null
>         \rounded-box \bold Prelude
>       }
>     }

Some commands may require an increase in the padding around the text; this is achieved with some markup commands exhaustively described in Align.

>     \markup \fill-line {
>       \center-column {
>         \box "Charles Ives (1874 - 1954)"
>         \null
>         \box \pad-markup #2 "THE UNANSWERED QUESTION"
>         \box \pad-x #8 "A Cosmic Landscape"
>         \null
>       }
>     }
>     \markup \column {
>       \line {
>         \hspace #10
>         \box \pad-to-box #'(-5 . 20) #'(0 . 5)
>           \bold "Largo to Presto"
>       }
>       \pad-around #3
>           "String quartet keeps very even time,
>     Flute quartet keeps very uneven time."
>     }

Other graphic elements or symbols may be printed without requiring any text. As with any markup expression, such objects can be combined.

>     \markup {
>       \combine
>         \draw-circle #4 #0.4 ##f
>         \filled-box #'(-4 . 4) #'(-0.5 . 0.5) #1
>       \hspace #5

>       \center-column {
>         \triangle ##t
>         \combine
>           \draw-line #'(0 . 4)
>           \arrow-head #Y #DOWN ##f
>       }
>     }

Advanced graphic features include the ability to include external image files converted to the Encapsulated PostScript format (eps), or to directly embed graphics into the input file, using native PostScript code. In such a case, it may be useful to explicitly specify the size of the drawing, as demonstrated below:

>     c1^\markup {
>       \combine
>         \epsfile #X #10 #"./context-example.eps"
>         \with-dimensions #'(0 . 6) #'(0 . 10)
>         \postscript #"
>           -2 3 translate
>           2.7 2 scale
>           newpath
>           2 -1 moveto
>           4 -2 4 1 1 arct
>           4 2 3 3 1 arct
>           0 4 0 3 1 arct
>           0 0 1 -1 1 arct
>           closepath
>           stroke"
>       }
>     c

An exhaustive list of graphics-specific commands can be found in Graphic.

#### See also

Notation Reference: Graphic, Editorial annotations, Align.

Snippets: Text.

Internals Reference: TextScript.

Installed Files: ‘`scm/define-markup-commands.scm`’, ‘`scm/stencil.scm`’.

#### Music notation inside markup

Various musical notation elements may be added to a score, inside a markup object.

Notes and accidentals can be entered using markup commands:

>     a2 a^\markup {
>       \note #"4" #1
>       =
>       \note-by-number #1 #1 #1.5
>     }
>     b1_\markup {
>       \natural \semiflat \flat
>       \sesquiflat \doubleflat
>     }
>     \glissando
>     a1_\markup {
>       \natural \semisharp \sharp
>       \sesquisharp \doublesharp
>     }
>     \glissando b

Other notation objects may also be printed in markup mode:

>     g1 bes
>     ees-\markup {
>       \finger 4
>       \tied-lyric #"~"
>       \finger 1
>     }
>     fis_\markup { \dynamic rf }
>     bes^\markup {
>       \beam #8 #0.1 #0.5
>     }
>     cis
>     d-\markup {
>       \markalphabet #8
>       \markletter #8
>     }

More generally, any available musical symbol may be included separately in a markup object, as demonstrated below; an exhaustive list of these symbols and their names can be found in The Feta font.

>     c2
>     c'^\markup { \musicglyph #"eight" }
>     c,4
>     c,8._\markup { \musicglyph #"clefs.G_change" }
>     c16
>     c2^\markup { \musicglyph #"timesig.neomensural94" }

Another way of printing non-text glyphs is described in Fonts explained. This is useful for printing braces of various sizes.

The markup mode also supports diagrams for specific instruments:

>     c1^\markup {
>       \fret-diagram-terse #"x;x;o;2;3;2;"
>     }
>     c^\markup {
>       \harp-pedal #"^-v|--ov^"
>     }
>     c
>     c^\markup {
>       \combine
>         \musicglyph #"accordion.discant"
>         \combine
>           \raise #0.5 \musicglyph #"accordion.dot"
>           \raise #1.5 \musicglyph #"accordion.dot"
>     }

Such diagrams are documented in Instrument Specific Markup.

A whole score can even be nested inside a markup object. In such a case, the nested `\score` block must contain a `\layout` block, as demonstrated here:

>     c4 d^\markup {
>       \score {
>         \relative c' { c4 d e f }
>         \layout { }
>       }
>     }
>     e f |
>     c d e f

An exhaustive list of music notation related commands can be found in Music.

#### See also

Notation Reference: Music, The Feta font, Fonts explained.

Snippets: Text.

Internals Reference: TextScript.

Installed Files: ‘`scm/define-markup-commands.scm`’, ‘`scm/fret-diagrams.scm`’, ‘`scm/harp-pedals.scm`’.

#### Multi-page markup

Although standard markup objects are not breakable, a specific syntax makes it possible to enter lines of text that can spread over multiple pages:

>     \markuplines {
>       \justified-lines {
>         A very long text of justified lines.
>         ...
>       }
>       \wordwrap-lines {
>         Another very long paragraph.
>         ...
>       }
>       ...
>     }

This syntax accepts a list of markups, that can be

- the result of a markup list command,
- a list of markups,
- a list of markup lists.

An exhaustive list of markup list commands can be found in Text markup list commands.

#### See also

Notation Reference: Text markup list commands,

Snippets: Text.

Extending: New markup list command definition.

Internals Reference: TextScript.

Installed Files: ‘`scm/define-markup-commands.scm`’.

#### Predefined commands

`\markuplines`.

其它语言：deutsch, español, français, 日本語。

#### LilyPond — Notation Reference