Previous: Font selection, Up: Tuning output


4.17.5 Text markup

LilyPond has an internal mechanism to typeset texts. You can access it with the keyword \markup. Within markup mode, you can enter texts similar to lyrics: simply enter them, surrounded by spaces: 

      c1^\markup { hello }
      c1_\markup { hi there }
      c1^\markup { hi \bold there, is \italic anyone home? }

[picture of music]

The markup in the example demonstrates font switching commands. The command \bold and \italic only apply to the first following word; enclose a set of texts with braces to apply a command to more words: 

       \markup { \bold { hi there } }

For clarity, you can also do this for single arguments, e.g. 

       \markup { is \italic { anyone } home }

The following size commands set absolute sizes:

\teeny
\tiny
\small
\large
\huge

You can also make letter larger or smaller relative to their neighbors, with the commands \larger and \smaller. The following font change commands are defined:

\dynamic
changes to the font used in dynamic signs. This font does not contain all characters of the alphabet, so when producing “piu f”, the “piu” should be done in a different font.
\number
changes to the font used in time signatures. It only contains numbers and a few punctuation marks.
\italic
changes font-shape to italic.
\bold
changes font-series to bold.

Raising and lowering texts can be done with \super and \sub: 

      c1^\markup { E "=" mc \super "2" }

[picture of music]

If you want to give an explicit amount for lowering or raising, use \raise. This command takes a Scheme valued first argument, and a markup object as second argument: 

      c1^\markup { C \small \raise #1.0 \bold { "9/7+" }}

[picture of music]

The argument to \raise is the vertical displacement amount, measured in (global) staff spaces. \raise and \super raise objects in relation to their surrounding markups. They cannot be used to move a single text up or down, when it is above or below a note, since the mechanism that positions it next to the note cancels any vertical shift. For vertical positioning, use the padding and/or extra-offset properties.

Other commands taking single arguments include

\bracket, \hbracket
Bracket the argument markup with normal and horizontal brackets respectively.
\musicglyph
This is converted to a musical symbol, e.g. \musicglyph #"accidentals-0" will select the natural sign from the music font. See The Feta font for a complete listing of the possible glyphs.
\char
This produces a single character, e.g. \char #65 produces the letter 'A'.
\note log dots dir
This produces a note with a stem pointing in dir direction, with duration log log and dots augmentation dots. The duration log is the negative 2-logarithm of the duration denominator. For example, a quarter note has log 2, an eighth note 3 and a breve has log -1.
\hspace #amount
This produces a invisible object taking horizontal space. 
          \markup { A \hspace #2.0 B }

will put extra space between A and B, on top of the space that is normally inserted before elements on a line.

\fontsize #size
This sets the relative font size, eg. 
          A \fontsize #2 { B C } D

This will enlarge the B and the C by two steps.

\translate #(cons x y)
This translates an object. Its first argument is a cons of numbers 
          A \translate #(cons 2 -3) { B C } D

This moves `B C' 2 spaces to the right, and 3 down.

\magnify #mag
This sets the font magnification for the its argument. In the following example, the middle A will be 10% larger: 
          A \magnify #1.1 { A } A

\override #(key . value)
This overrides a formatting property for its argument. The argument should be a key/value pair, e.g. 
            m \override #'(font-family . math) m m

In markup mode you can compose expressions, similar to mathematical expressions, XML documents and music expressions. The braces group notes into horizontal lines. Other types of lists also exist: you can stack expressions grouped with <, and > vertically with the command \column. Similarly, \center aligns texts by their center lines: 

      c1^\markup { \column < a bbbb c > }
      c1^\markup { \center < a bbbb c > }
      c1^\markup { \line < a b c > }

[picture of music]

The markup mechanism is extensible. Refer to scm/new-markup.scm for more information.

See also

Markup-functions (lilypond-internals), and scm/new-markup.scm.

Bugs

Text layout is ultimately done by TeX, which does kerning of letters. LilyPond does not account for kerning, so texts will be spaced slightly too wide.

Syntax errors for markup mode are confusing.

Markup texts cannot be used in the titling of the \header field. Titles are made by LaTeX, so LaTeX commands should be used for formatting.

This page is for LilyPond-2.0.3 (stable-branch).
Report errors to <bug-lilypond@gnu.org>.