[ << Text ]	[Top][Contents][Index]	[ Vocal music >> ]
[ < Formatting text ]	[ Up: Formatting text ]	[ Selecting font and font size > ]

8.2.1 Text markup introduction

A \markup or \markuplist block is used to typeset text with an extensible syntax called “markup mode”. Such blocks can be used in many contexts (see Text objects overview).

In markup mode, words are written as-is. A single word does not need any quotes.

\markup intenso

Several words can be grouped together by enclosing them in quotes.

\markup "molto intenso"

Apart from grouping, quoting also allows writing special characters such as ‘\’ and ‘#’ without affecting the formatting of the text. Double quotation marks themselves may be printed by preceding them with backslashes.

\relative {
  a'1^"\italic markup..."
  a_\markup { \italic "... prints \"italic\" letters!" }
  a a
}

Formatting is achieved through markup commands. Their name is written preceded by a backslash. They expect a number of arguments specific to the command. For an exhaustive list of \markup-specific commands, see Text markup commands.

\markup \italic "string. assai"
\markup \with-color "red" intenso

Markup commands can be nested. The markup block ends when all commands have received their arguments.

\markup \with-color "red" \italic intenso

Several markup expressions can be grouped together within braces to form a so-called markup list. Without further formatting, the elements of a markup list are typeset in a row.

\markup { molto \italic intenso }

Some commands do not expect a markup but a markup list, allowing for more complex text arrangements than printing in a row.

\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  "Karl Amadeus Hartmann"
}

Also, some commands do not return a markup but a markup list. The result can then be used where a markup list is expected. For a list of these commands, see Text markup list commands.

\markup \string-lines
    "Twinkle, twinkle, little star,
     How I wonder what you are!"

\markup \center-column \string-lines
    "Twinkle, twinkle, little star,
     How I wonder what you are!"

Elements of a nested markup list are simply treated as elements of the main markup list.

\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  { Karl Amadeus \smallCaps Hartmann }
}

To group elements of a nested markup list in a row, apply the \line command to the markup list. This stacks elements from the markup list horizontally into a single markup.

\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  \line { Karl Amadeus \smallCaps Hartmann }
}

A special feature is the handling of commands taking markups when applied to markup lists. When a command expects a markup as its last argument, and a markup list is given for this argument, the markup command is applied to each of the individual markups in the list.

\markup \box { Karl Amadeus \smallCaps Hartmann }

In this case, the result is in turn a markup list, which can be passed to a command expecting a markup list, or to one expecting a markup, with again the mapping behavior described above in the latter case.

\markup \center-column \box { Karl Amadeus \smallCaps Hartmann }
\markup \rotate #30 \box { Karl Amadeus \smallCaps Hartmann }

Apply \line to a markup list in order to make it treated as a single markup argument.

\markup \box { Karl Amadeus \smallCaps Hartmann }
\markup \box \line { Karl Amadeus \smallCaps Hartmann }

When the entire content of a \markup expression is a markup list, it is implicitly typeset using the \line command. Thus, elements are stacked horizontally and grouped as a single, unbreakable text block. The \markuplist command acts differently: it expects a markup list, and prints the individual markups on the page, stacking them vertically, and allowing page breaks. The following example illustrates this difference.

\markup \box \wordwrap {
  Lorem ipsum dolor sit amet, consectetur
  adipisicing elit, sed do eiusmod tempor incididunt
  ut labore et dolore magna aliqua.  Ut enim ad minim
  veniam, quis nostrud exercitation ullamco laboris
  nisi ut aliquip ex ea commodo consequat.
}

\markuplist \box \wordwrap-lines {
  Lorem ipsum dolor sit amet, consectetur
  adipisicing elit, sed do eiusmod tempor incididunt
  ut labore et dolore magna aliqua.  Ut enim ad minim
  veniam, quis nostrud exercitation ullamco laboris
  nisi ut aliquip ex ea commodo consequat.
}

Markups can be stored in variables, to be reused in any context where a markup is accepted. For example, such a variable can be directly attached to notes:

allegro = \markup \bold \large Allegro

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

The \etc syntax allows to define custom shorthands usable as markup commands.

\markup reddish = \markup \with-color "tomato" \etc

\markup { molto \reddish intenso }

The inner workings of markup commands and how to implement more complex ones is explained in Markup functions.

See also

Notation Reference: Text objects overview, Text markup commands, Text markup list commands.

Extending LilyPond: Markup functions.

Installed Files: scm/markup.scm, scm/define-markup-commands.scm.

Snippets: Text.

Internals Reference: TextScript.

Known issues and warnings

Syntax error messages for markup mode can be confusing.

---

[ << Text ]	[Top][Contents][Index]	[ Vocal music >> ]
[ < Text markup introduction ]	[ Up: Formatting text ]	[ Text alignment > ]

8.2.2 Selecting font and font size

Basic font switching is supported in markup mode:

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

The global text size to be used in markups can be set with the text-font-size paper variable. This is useful to adjust to a different main font that might appear smaller or larger despite of having the same nominal font sizes. The value is given in points (without specifying a unit); the default value depends on the staff height and is computed as (staff-height / 20 * 11).

See Distances and measurements for more information on dimensions used by LilyPond.

\score {
  { f'^"Default text size" }
  \layout { text-font-size = 10 }
}

\score {
  { f'^"Default text size" }
  \layout { text-font-size = 20 }
}

The font size can be altered, relative to the global text size, in a number of different ways.

It can be set to predefined size.

\relative b' {
  b1_\markup { \huge Sinfonia }
  b1^\markup { \teeny da }
  b1-\markup { \normalsize camera }
}

It can be set relative to its previous value.

\relative b' {
  b1_\markup { \larger Sinfonia }
  b1^\markup { \smaller da }
  b1-\markup { \magnify #0.6 camera }
}

It can be increased or decreased relative to the value set by the global staff size.

\relative b' {
  b1_\markup { \fontsize #-2 Sinfonia }
  b1^\markup { \fontsize #1 da }
  b1-\markup { \fontsize #3 camera }
}

It can also be set to a fixed point size, regardless of the global staff size.

\relative b' {
  b1_\markup { \abs-fontsize #20 Sinfonia }
  b1^\markup { \abs-fontsize #8 da }
  b1-\markup { \abs-fontsize #14 camera }
}

If the text includes spaces, then it is best to put it all inside quote marks, so that the size of each space is appropriate for the size of the other characters.

\markup \fontsize #6 \bold { Sinfonia da camera }
\markup \fontsize #6 \bold { "Sinfonia da camera" }

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. A serif font is selected by default 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 \serif 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 markup.

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 markup, New dynamic marks, Manual repeat marks, Fonts.

Installed Files: scm/define-markup-commands.scm.

Snippets: Text.

Internals Reference: TextScript.

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 ]	[Top][Contents][Index]	[ Vocal music >> ]
[ < Selecting font and font size ]	[ Up: Formatting text ]	[ Graphic notation inside markup > ]

8.2.3 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. That example also demonstrates various syntactically correct ways of placing the alignment commands:

\relative {
  d''1-\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:

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

Lastly, words and any other objects may be moved horizontally by preceding them with \hspace. Negative values are also supported and move any objects that follow into the opposite direction. Here, we put \hspace into a box to better show its effect.

\relative {
  d''1-\markup { poco }
  f
  d-\markup \concat { \with-color #darkred \box \hspace #4 poco }
  f
  d-\markup \concat { \with-color #darkred \box \hspace #-4 poco }
  f
  d-\markup \concat { \with-color #darkred \box \hspace #10 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 can be set in a similar way. As stated above, markup objects can be moved as a whole; however, it is also possible to move specific elements inside a markup block.

\relative {
  d'2^\markup {
    Acte I
    \raise #2 { Scène 1 }
  }
  a'
  g_\markup {
    \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:

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

Note that \vspace can not be used in general to move arbitrary objects up or down within a \column markup due to the way the latter is implemented. The following naïve approach thus fails.

\relative {
  d'2^\markup {
    Acte I
    \column {
      \vspace #-2
      "Scène 1"
    }
  }
  a'
  g_\markup \column {
    \vspace #1
    "Très modéré"
  }
  a
  d,^\markup \column {
    "Une forêt."
    \vspace #2
  }
  a'4 a g2 a
}

What actually works is to put \vspace between two objects that have non-empty extents.

\relative {
  d'2^\markup {
    Acte I
    \column {
      " "
      \vspace #-2
      "Scène 1"
    }
  }
  a'
  g_\markup \column {
    " "
    \vspace #1
    "Très modéré"
  }
  a
  d,^\markup \column {
    "Une forêt."
    \vspace #2
    " "
  }
  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 }
}

Elements may be spread to fill any specified width by overriding the line-width property. By default it is set to #f which indicates the entire line:

\markup {
  \column {
    \fill-line { left center right }
    \null
    \override #'(line-width . 30)
    \fill-line { left center right }
  }
}

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 Markup for text alignment.

See also

Learning Manual: Moving objects.

Notation Reference: Markup for text alignment, Text marks.

Installed Files: scm/define-markup-commands.scm.

Snippets: Text.

Internals Reference: TextScript.

---

[ << Text ]	[Top][Contents][Index]	[ Vocal music >> ]
[ < Text alignment ]	[ Up: Formatting text ]	[ Music notation inside markup > ]

8.2.4 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 Markup for text alignment.

\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"
  }
  \box \pad-around #3 "String quartet keeps very even 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:

c'1^\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 Graphical markup.

See also

Notation Reference: Markup for text alignment, Dimensions, Editorial annotations, Graphical markup.

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

Snippets: Text.

Internals Reference: TextScript.

---

[ << Text ]	[Top][Contents][Index]	[ Vocal music >> ]
[ < Graphic notation inside markup ]	[ Up: Formatting text ]	[ Fonts > ]

8.2.5 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:

a'2 a'^\markup {
  \note {4} #1
  =
  \note-by-number #1 #1 #1.5
}
b'1_\markup {
  \natural \semiflat \flat
  \sesquiflat \doubleflat
}
\glissando
a'1_\markup {
  \natural \semisharp \sharp
  \sesquisharp \doublesharp
}
\glissando b'

Other notation objects may also be printed in markup mode:

\relative {
  g1 bes
  ees\finger \markup \tied-lyric "4~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 Emmentaler font.

\relative {
  c''2
  c'^\markup { \musicglyph "eight" }
  c,4_\markup { \left-brace #40 }
  c,8._\markup { \musicglyph "clefs.G_change" }
  c16
  c2^\markup { \musicglyph "timesig.neomensural94" }
}

The markup mode also supports diagrams for specific instruments:

\relative {
  c''1^\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:

\relative {
  c'4 d^\markup {
    \score {
      \relative { c'4 d e f }
    }
  }
  e f |
  c d e f
}

An exhaustive list of music notation related commands can be found in Markup for music and musical symbols.

See also

Notation Reference: Markup for music and musical symbols, The Emmentaler font.

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

Snippets: Text.

Internals Reference: TextScript.

Known issues and warnings

Vertical spacing of a \score inside a markup object is controlled by baseline-skip. Any \paper settings are ignored.