@c -*- coding: utf-8; mode: texinfo; -*-
@ignore
    Translation of GIT committish: FILL-IN-HEAD-COMMITTISH

    When revising a translation, copy the HEAD committish of the
    version that you are working on.  For details, see the Contributors'
    Guide, node Updating translation committishes..
@end ignore

@c \version "2.21.0"

@node Text
@section Text

@lilypondfile[quote]{snippets/text-headword.ly}

This section explains how to include text (with various
formatting) in music scores.

@menu
* Writing text::
* Formatting text::
* Fonts::
@end menu

@node Writing text
@subsection Writing text

This section introduces different ways of adding text to a score.

@cindex text, other languages
@warning{To write accented and special text (such as characters
from other languages), simply insert the characters directly into
the LilyPond file.  The file must be saved as UTF-8.  For more
information, see @ref{Text encoding}.}

@menu
* Text objects overview::
* Text scripts::
* Text spanners::
* Section labels::
* Text marks::
* Separate text::
@end menu


@node Text objects overview
@unnumberedsubsubsec Text objects overview

@funindex \markup
@cindex text object
@cindex markup object
@cindex object, markup

Simple text objects are entered as strings between double quotes
(these are optional for a single word).  The markup mode is a
richer tool that can accept a variety of advanced text formatting
and graphical enhancements, as detailed in @ref{Formatting text}.

As such, markup blocks may be used:
@itemize
@item
in any @code{TextScript} object (attached to notes with
@code{-}, @code{^} or@tie{}@code{_}); see @ref{Text scripts};

@item
as @q{spanners}, when some indications are prolonged over
several beats or bars; see @ref{Text spanners};

@item
in any mark printed above the score, such as
@code{RehearsalMark} or @code{MetronomeMark} objects respectively
introduced with the @code{\mark} or @code{\tempo} keywords;
see @ref{Text marks};

@item
as stand-alone text blocks, entered at the top level outside of any
@code{\score} block (in this specific case the @code{\markup} or
@code{\markuplist} command is mandatory, and cannot be omitted in
favor of a simple text string between double quotes); see
@ref{Separate text};

@item
in any definition inside the @code{\header} block (e.g.,
@code{title}, @code{subtitle}, @code{composer}), or in specific
elements defined inside the @code{\paper} block such as
@code{evenHeaderMarkup} for page numbers.  This is explained in
@ref{Titles and headers}.
@end itemize

Many other text-based objects may be entered as markup blocks,
even if that is not their primary use.
@itemize
@item
Fingerings may easily be replaced with markup blocks, if
introduced with the @code{\finger} command; see
@ref{Fingering instructions}.

@item
Lyric syllables may be formatted through the @code{\markup}
command; see @ref{Common notation for vocal music}.

@item
Chord names are in fact defined as markup blocks, and therefore
may be redefined in the same way for customizing chord modifiers
or chord exceptions; see @ref{Displaying chords}.

@item
Dynamics are usually entered in a simple way; however it is possible
to define @ref{New dynamic marks} as markup objects.  Some dynamics
such as @emph{crescendo} are printed as spanners and may be redefined
through properties such as @code{crescendoText}; see
@ref{Dynamics}.

@item
Less common objects are also made of markup blocks, such as
@ref{Balloon help} indications.
@end itemize

In fact, it is possible to use @code{\markup} to customize the appearance of
virtually any graphical object (or @q{grob}), by overriding either its
@code{text} property if it has one, or its @code{stencil} property.  Some of
the logic that makes this a possibility is explained in
@ressay{Flexible architecture}.

The following example illustrates the ubiquity of markup blocks, not only
as some of the objects listed above, but also by replacing musical
objects with text objects through various methods.

@lilypond[quote, verbatim,line-width=4\in]
\header { title = \markup "Header" }

dyn =
#(make-dynamic-script #{ \markup \text "DynamicText" #})

\markup \box "Top-level markup"

\score {
  <<
    \new ChordNames
    \with {
      majorSevenSymbol = \markup "majorSevenSymbol"
    }
    \chordmode { c1:maj7 }
    \new Staff {
      \tempo \markup "MetronomeMark"
      \textMark "TextMark"
      \once \override TupletNumber.text =
        \markup "TupletNumber"
      \tuplet 3/2 {
        \once \override NoteHead.stencil =
          #ly:text-interface::print
        \once \override NoteHead.text =
          \markup \lower #0.5 "NoteHead"
        c''8^\markup \italic "TextScript"
        a'\finger \markup \text "Fingering"
        \once \override Rest.stencil =
          #(lambda (grob)
             (grob-interpret-markup grob #{
               \markup  "Rest"
               #}))
        r
      }
    }
    \new Lyrics \lyricmode {
      \markup \smallCaps "LyricText" 1
    }
    \new Dynamics { s1\dyn }
  >>
}
@end lilypond

@morerefs
Notation Reference:
@ref{Formatting text},
@ref{Text scripts},
@ref{Text spanners},
@ref{Text marks},
@ref{Separate text},
@ref{Fingering instructions},
@ref{Common notation for vocal music},
@ref{Displaying chords},
@ref{New dynamic marks},
@ref{Dynamics},
@ref{Balloon help}.

Essay on automated music engraving:
@ressay{Flexible architecture}.

Snippets:
@rlsr{Text}.
@endmorerefs


@node Text scripts
@unnumberedsubsubsec Text scripts

@cindex text script
@cindex text item, non-empty
@cindex non-empty text
@cindex quoted text

Simple @qq{quoted text} indications may be added to a score, as
demonstrated in the following example.  Such indications may be
manually placed above or below the staff, using the syntax described
in @ref{Direction and placement}.

@lilypond[quote,verbatim]
\relative { a'8^"pizz." g f e a4-"scherz." f }
@end lilypond

This syntax is actually a shorthand; more complex text formatting may be
added to a note by explicitly using a @code{\markup} block, as described
in @ref{Formatting text}.

@lilypond[quote,verbatim]
\relative {
  a'8^\markup { \italic pizz. } g f e
  a4_\markup { \tiny scherz. \bold molto } f }
@end lilypond

By default, text indications do not influence the note spacing. However,
their widths can be taken into account: in the following example, the
first text string does not affect spacing, whereas the second one does.

@lilypond[quote,verbatim]
\relative {
  a'8^"pizz." g f e
  \textLengthOn
  a4_"scherzando" f
}
@end lilypond

In addition to text scripts, articulations can be attached to notes.
For more information, see @ref{Articulations and ornamentations}.

For more information about the relative ordering of text scripts and
articulations, see @rlearning{Placement of objects}.

@funindex \textLengthOn
@funindex \textLengthOff

@predefined
@code{\textLengthOn},
@code{\textLengthOff}.
@endpredefined

@morerefs
Learning Manual:
@rlearning{Placement of objects}.

Notation Reference:
@ref{Formatting text},
@ref{Direction and placement},
@ref{Articulations and ornamentations}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextScript}.
@endmorerefs

@cindex text, outside margin
@cindex margin, text running over
@cindex text, keeping inside margin
@cindex lyrics, keeping inside margin

@knownissues
Checking to make sure that text scripts and lyrics are within the
margins requires additional calculations. In cases where slightly faster
performance is desired, use

@example
\override Score.PaperColumn.keep-inside-line = ##f
@end example


@node Text spanners
@unnumberedsubsubsec Text spanners

@cindex text spanner

Some performance indications, e.g., @notation{rallentando} or
@notation{accelerando}, are written as text and are extended over
multiple notes with dotted lines.  Such objects, called
@qq{spanners}, may be created from one note to another using the
following syntax:

@lilypond[verbatim,quote]
\relative {
  \override TextSpanner.bound-details.left.text = "rit."
  b'1\startTextSpan
  e,\stopTextSpan
}
@end lilypond

@cindex text spanner, formatting
@cindex formatting, text spanner

@noindent
The string to be printed is set through object properties.  By default
it is printed in italic characters, but different formatting can be
obtained using @code{\markup} blocks, as described in
@ref{Formatting text}.

@lilypond[quote,verbatim]
\relative {
  \override TextSpanner.bound-details.left.text =
    \markup { \upright "rit." }
  b'1\startTextSpan c
  e,\stopTextSpan
}
@end lilypond

The line style, as well as the text string, can be defined as an
object property.  This syntax is described in @ref{Line styles}.

@funindex \textSpannerUp
@funindex \textSpannerDown
@funindex \textSpannerNeutral


@predefined
@code{\textSpannerUp},
@code{\textSpannerDown},
@code{\textSpannerNeutral}.
@endpredefined

@knownissues
LilyPond is only able to handle one text spanner per voice.

The texts at the bounds of a text spanner may collide.

@lilypond[verbatim,quote]
{
  \once \override TextSpanner.bound-details.left.text = "The text is"
  \once \override TextSpanner.bound-details.right.text = "too long"
  c'2\startTextSpan d'2\stopTextSpan
}
@end lilypond

Workarounds can be found in @ref{Horizontal spacing}.

@snippets

@cindex dynamics, text spanner, customize
@cindex text spanner, dynamics, customize
@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/dynamics-text-spanner-postfix.ly}

@lilypondfile[verbatim,quote,texidoc,doctitle]
{snippets/dynamics-custom-text-spanner-postfix.ly}


@morerefs
Notation Reference:
@ref{Line styles},
@ref{Dynamics},
@ref{Formatting text}.

Snippets:
@rlsr{Text},
@rlsr{Expressive marks}.

Internals Reference:
@rinternals{TextSpanner}.
@endmorerefs


@node Section labels
@unnumberedsubsubsec Section labels


@cindex section label
@cindex text, on bar line

@funindex \sectionLabel

The @code{\sectionLabel} command marks the beginning of a named
passage.  It is well suited for use at a section division created
with @code{\section}, but it does not imply @code{\section} and
may be used alone.

@lilypond[verbatim,quote]
\fixed c' {
  \sectionLabel "Verse"
  c2 g
  \section
  \sectionLabel "Chorus"
  g2 c
  \bar "|."
}
@end lilypond

@morerefs
Notation Reference:
@ref{Formatting text},
@ref{Rehearsal marks},
@ref{Section divisions}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{SectionLabel},
@rinternals{SectionLabelEvent}.
@endmorerefs


@node Text marks
@unnumberedsubsubsec Text marks

@cindex text mark
@cindex mark, text
@cindex text, on bar line
@cindex text, between notes
@cindex text, at beginning of line
@cindex bar line, symbols on
@cindex bar line, text over
@cindex text, at end of score

@funindex \textMark
@funindex \textEndMark
@funindex \markup


Text marks are textual objects that, unlike text scripts
(@pxref{Text scripts}), are not printed over notes but between
notes, often aligned to a bar line.

@funindex \mark

@warning{Older LilyPond versions used the @code{@bs{}mark} command for
text marks, even though it is primarily intended for rehearsal
marks (@pxref{Rehearsal marks}).  The @code{@bs{}textMark} and
@code{@bs{}textEndMark} commands are better suited for text marks with
regard to their default settings as well as the ability to have
several text marks at the same moment.  It is therefore
recommended to use @code{@bs{}textMark} and @code{@bs{}textEndMark}
instead of @code{@bs{}mark "Text"} or @code{@bs{}mark @bs{}markup @dots{}}.
Note that if converting code that uses @code{@bs{}mark} for text
marks, overrides using @code{RehearsalMark} should be changed to
@code{TextMark}.}

Before using text marks, it is recommended to seek a more specific
command, if available.  For text that identifies a section, use
@code{\sectionLabel} (@pxref{Section labels}).  For jump
instructions, use @code{\jump} (@pxref{Manual repeat marks}).
These commands have different default layout settings, and they
create separate objects which can be styled differently from
generic text marks in stylesheets.

A text mark is entered using either @code{\textMark} or
@code{\textEndMark}.  The @code{\textMark} command draws a
left-aligned mark.

@lilypond[verbatim,quote]
\fixed c'' {
  \textMark "Fl. 1 solo"
  c4 e g2
  \textMark "A due"
  e4 g c'2
}
@end lilypond

If a line break occurs at the point @code{\textMark} is used, the
text appears on the next system.

@lilypond[verbatim,quote,ragged-right]
\fixed c'' {
  \textMark "Fl. 1 solo"
  c4 e g2
  \break
  \textMark "A due"
  e4 g c'2
}
@end lilypond

Unlike @code{\textMark}, @code{\textEndMark} creates a
right-aligned mark.  If it occurs on a line break, it is printed
on the preceding system.

@lilypond[verbatim,quote,ragged-right]
\fixed c' {
  \repeat volta 2 {
    c4 e8 f g2
    e4 f8 g c'2
    \textEndMark "ad lib"
  }
  \break
  c'4 8 8 4 8 8
  c'1
}
@end lilypond

Complex text formatting may be added using a @code{\markup} block
(@pxref{Formatting text}).

@lilypond[quote,verbatim]
\relative {
  <c' e>1
  \textMark \markup { \italic { colla parte } }
  <d f>2 <e g>
  <c f aes>1
}
@end lilypond

@funindex \markLengthOn
@funindex \markLengthOff

The @code{\markLengthOn} and @code{\markLengthOff} commands
(@pxref{Metronome marks}) can also be used on text marks.

@lilypond[verbatim,quote]
{
  \mark \default
  c'2 2
  \textEndMark "long mark text"
  \markLengthOn
  2 2
  \mark \default
  2 2
  \textEndMark "long mark text"
}
@end lilypond

@cindex text mark, below staff

Text marks may be printed below the staff.

@lilypond[verbatim,quote]
\fixed c' {
  c4 g c'8 b c4 e' c' c2
  c4 g c'8 b c4 e' c' g2
  e'4 c' c'8 b c'4
  g4 c' c2~ c1
  \tweak direction #DOWN
    \tweak font-size #-1
      \textEndMark "Composed on November 13th, 2020"
}
@end lilypond

@cindex text mark, vertical stacking

There can be several text marks at the same moment.  Their
stacking order can be overridden using the
@code{outside-staff-priority} property (@pxref{Vertical collision
avoidance}).  Alternatively, a single text mark with
@code{\markup \column @{ @dots{} @} } can achieve the same effect.

@lilypond[verbatim,quote]
\fixed c' {
  \repeat volta 2 {
    c4 g c'8 b c4 e' c' c2
    \textEndMark "ad lib."
    \tweak outside-staff-priority 1200
      \tweak font-size -1
        \textEndMark "2nd time a due"
  }
}
@end lilypond

@cindex text mark, alignment

The alignment of a text mark can be changed.

@lilypond[verbatim,quote]
{
  c'8 8 8 8 8 8 8 8
  \textMark \markup \column {
    \line { Left-aligned mark }
    \line { (default for \concat { \typewriter "\\textMark" ) } }
  }
  d'8 8 8 8 8 8 8 8
}

{
  c'8 8 8 8 8 8 8 8
  \tweak self-alignment-X #CENTER
    \textMark "Centered mark"
  d'8 8 8 8 8 8 8 8
}

{
  c'8 8 8 8 8 8 8 8
  \tweak self-alignment-X #RIGHT
    \textMark \markup \right-column {
      \line { Right-aligned mark }
      \line { (default for \concat { \typewriter "\\textEndMark" ) } }
    }
  d'8 8 8 8 8 8 8 8
}
@end lilypond


@predefined
@code{\textMark},
@code{\textEndMark},
@code{\markLengthOn},
@code{\markLengthOff}.
@endpredefined

@snippets

@c Also in 'Rehearsal marks'.
@cindex text mark, on every staff
@funindex Text_mark_engraver
@funindex Staff_collecting_engraver
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{snippets/printing-marks-on-every-staff.ly}


@morerefs
Notation Reference:
@ref{Metronome marks},
@ref{Rehearsal marks},
@ref{Section labels},
@ref{Formatting text},
@ref{Music notation inside markup},
@ref{The Emmentaler font}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextMarkEvent},
@rinternals{Text_mark_engraver},
@rinternals{TextMark}.
@endmorerefs


@node Separate text
@unnumberedsubsubsec Separate text

@cindex separate text
@cindex text, separate
@cindex stand-alone text
@cindex top-level text
@cindex text, top-level
@cindex text, stand-alone

@funindex \markup

A @code{\markup} or @code{\markuplist} block can exist by itself,
outside of any @code{\score} block, as a @qq{top-level
expression}.  This syntax is described in @ref{File structure}.

@lilypond[verbatim,quote]
\markup {
  Tomorrow, and tomorrow, and tomorrow...
}
@end lilypond

@noindent
This allows printing text separately from the music, which is
particularly useful when the input file contains several music pieces,
as described in @ref{Multiple scores in a book}.

@lilypond[quote,verbatim]
\score {
  c'1
}
\markup {
  Tomorrow, and tomorrow, and tomorrow...
}
\score {
  c'1
}
@end lilypond

Using @code{\markuplist}, separate text blocks can be spread over
multiple pages, making it possible to print text documents or
books entirely within LilyPond.  For a description of this feature
and the specific syntax it requires, @pxref{Text markup
introduction}.

@funindex \markup
@funindex \markuplist

@predefined
@code{\markup},
@code{\markuplist}.
@endpredefined


@snippets

@cindex text, in columns
@cindex column, text
@cindex two-column text
@cindex markup, two-column
@lilypondfile[verbatim,quote,ragged-right,texidoc,doctitle]
{snippets/stand-alone-two-column-markup.ly}


@morerefs
Notation Reference:
@ref{Formatting text},
@ref{File structure},
@ref{Multiple scores in a book}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextScript}.
@endmorerefs


@node Formatting text
@subsection Formatting text

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

@menu
* Text markup introduction::
* Selecting font and font size::
* Text alignment::
* Graphic notation inside markup::
* Music notation inside markup::
@end menu

@node Text markup introduction
@unnumberedsubsubsec Text markup introduction

@cindex markup
@cindex text markup
@cindex markup text
@cindex typeset text

@funindex \markup

A @code{\markup} or @code{\markuplist} block is used to typeset
text with an extensible syntax called @qq{markup mode}.  Such
blocks can be used in many contexts (@pxref{Text objects
overview}).

@cindex markup expression
@cindex expression, markup
@cindex markup syntax
@cindex syntax, markup

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

@lilypond[verbatim,quote]
\markup intenso
@end lilypond

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

@lilypond[verbatim,quote]
\markup "molto intenso"
@end lilypond

@cindex special character, in markup mode
@cindex markup mode, special characters
@cindex reserved character, printing
@cindex printing reserved character
@cindex printing special character
@cindex quoted text, in markup mode
@cindex markup mode, quoted text

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

@lilypond[quote,verbatim]
\relative {
  a'1^"\italic markup..."
  a_\markup { \italic "... prints \"italic\" letters!" }
  a a
}
@end lilypond

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
@code{\markup}-specific commands, @pxref{Text markup commands}.

@lilypond[verbatim,quote]
\markup \italic "string. assai"
\markup \with-color "red" intenso
@end lilypond

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

@lilypond[verbatim,quote]
\markup \with-color "red" \italic intenso
@end lilypond

@cindex markup list
@cindex list of markups

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

@lilypond[verbatim,quote]
\markup { molto \italic intenso }
@end lilypond

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

@lilypond[verbatim,quote]
\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  "Karl Amadeus Hartmann"
}
@end lilypond

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, @pxref{Text markup list commands}.

@lilypond[verbatim,quote]
\markup \string-lines
    "Twinkle, twinkle, little star,
     How I wonder what you are!"
@end lilypond

@lilypond[verbatim,quote]
\markup \center-column \string-lines
    "Twinkle, twinkle, little star,
     How I wonder what you are!"
@end lilypond

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

@lilypond[verbatim,quote]
\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  { Karl Amadeus \smallCaps Hartmann }
}
@end lilypond

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

@lilypond[verbatim,quote]
\markup \center-column {
  \bold "Des Simplicius Simplicissimus Jugend"
  \line { Karl Amadeus \smallCaps Hartmann }
}
@end lilypond

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.

@lilypond[verbatim,quote]
\markup \box { Karl Amadeus \smallCaps Hartmann }
@end lilypond

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.

@lilypond[verbatim,quote]
\markup \center-column \box { Karl Amadeus \smallCaps Hartmann }
\markup \rotate #30 \box { Karl Amadeus \smallCaps Hartmann }
@end lilypond

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

@lilypond[verbatim,quote]
\markup \box { Karl Amadeus \smallCaps Hartmann }
\markup \box \line { Karl Amadeus \smallCaps Hartmann }
@end lilypond

@cindex multi-page markup
@cindex markup, multi-page
@cindex markup text, multi-page
@cindex text, spread over multiple pages
@cindex page breaks, within markup

@funindex \markuplist
@funindex \justified-lines
@funindex \wordwrap-lines

When the entire content of a @code{\markup} expression is a markup
list, it is implicitly typeset using the @code{\line} command.
Thus, elements are stacked horizontally and grouped as a single,
unbreakable text block.  The @code{\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.

@lilypond[quote,verbatim]
\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.
}
@end lilypond

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:

@lilypond[quote,verbatim]
allegro = \markup \bold \large Allegro

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

@funindex \etc

The @code{\etc} syntax allows to define custom shorthands usable
as markup commands.

@lilypond[quote,verbatim]
\markup reddish = \markup \with-color "tomato" \etc

\markup { molto \reddish intenso }
@end lilypond

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

@morerefs
Notation Reference:
@ref{Text objects overview},
@ref{Text markup commands},
@ref{Text markup list commands}.

Extending LilyPond:
@rextend{Markup functions}.

Installed Files:
@file{scm/markup.scm},
@file{scm/define-markup-commands.scm}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextScript}.
@endmorerefs

@knownissues
Syntax error messages for markup mode can be confusing.


@node Selecting font and font size
@unnumberedsubsubsec Selecting font and font size

@cindex font switching
@cindex changing font
@cindex switching font

@funindex \italic
@funindex \bold
@funindex \underline

Basic font switching is supported in markup mode:

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

@cindex font size
@cindex text size

@funindex \abs-fontsize
@funindex \fontsize
@funindex \smaller
@funindex \larger
@funindex \magnify

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

It can be set to predefined size.

@lilypond[quote,verbatim]
\relative b' {
  b1_\markup { \huge Sinfonia }
  b1^\markup { \teeny da }
  b1-\markup { \normalsize camera }
}
@end lilypond

It can be set relative to its previous value.

@lilypond[quote,verbatim]
\relative b' {
  b1_\markup { \larger Sinfonia }
  b1^\markup { \smaller da }
  b1-\markup { \magnify #0.6  camera }
}
@end lilypond

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

@lilypond[quote,verbatim]
\relative b' {
  b1_\markup { \fontsize #-2 Sinfonia }
  b1^\markup { \fontsize #1 da }
  b1-\markup { \fontsize #3 camera }
}
@end lilypond

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

@lilypond[quote,verbatim]
\relative b' {
  b1_\markup { \abs-fontsize #20 Sinfonia }
  b1^\markup { \abs-fontsize #8 da }
  b1-\markup { \abs-fontsize #14 camera }
}
@end lilypond

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.

@lilypond[quote,verbatim]
\markup \fontsize #6 \bold { Sinfonia da camera }
\markup \fontsize #6 \bold { "Sinfonia da camera" }
@end lilypond

@cindex subscript
@cindex superscript

@funindex \super
@funindex \sub
@funindex \normal-size-super

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:

@lilypond[quote,verbatim]
\markup {
  \column {
    \line { 1 \super st movement }
    \line { 1 \normal-size-super st movement
      \sub { (part two) }  }
  }
}
@end lilypond

@cindex font family

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.

@lilypond[quote,verbatim]
\markup {
  \column {
    \line { Act \number 1 }
    \line { \sans { Scene I. } }
    \line { \typewriter { Verona. An open place. } }
    \line { Enter \roman Valentine and Proteus. }
  }
}
@end lilypond

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

@c \concat is actually documented in Align (it is not
@c a font-switching command).  But we need it here. -vv

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:

@lilypond[quote,verbatim]
\markup {
  \column {
    \line {
      \concat { 1 \super st }
      movement
    }
    \line {
      \concat { \dynamic p , }
      \italic { con dolce espressione }
    }
  }
}
@end lilypond

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

Defining custom font sets is also possible, as explained in
@ref{Fonts}.

@funindex \teeny
@funindex \tiny
@funindex \small
@funindex \normalsize
@funindex \large
@funindex \huge
@funindex \smaller
@funindex \larger


@predefined
@code{\teeny},
@code{\tiny},
@code{\small},
@code{\normalsize},
@code{\large},
@code{\huge},
@code{\smaller},
@code{\larger}.
@endpredefined

@morerefs
Notation Reference:
@ref{Font},
@ref{New dynamic marks},
@ref{Manual repeat marks},
@ref{Fonts}.

Installed Files:
@file{scm/define-markup-commands.scm}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextScript}.
@endmorerefs

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


@node Text alignment
@unnumberedsubsubsec Text alignment

@cindex text, aligning
@cindex aligning text
@cindex aligning markup text
@cindex aligning markup
@cindex markup, aligning
@cindex markup text, aligning

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

@cindex text, horizontal alignment
@cindex horizontal text alignment

@funindex \left-align
@funindex \center-align
@funindex \right-align

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:

@lilypond[quote,verbatim]
\relative {
  d''1-\markup { poco }
  f
  d-\markup { \left-align poco }
  f
  d-\markup { \center-align { poco } }
  f
  d-\markup \right-align { poco }
}
@end lilypond

@funindex \halign

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

@lilypond[quote,verbatim]
\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 }
}
@end lilypond

@funindex \hspace
@cindex padding in markup, horizontal
@cindex horizontal padding in markup

Lastly, words and any other objects may be moved by preceding
them with padding.  Negative padding is also supported, and
will move any objects that follow in the opposite direction.
Although padding is normally invisible, in the following
example some commands have been added to make it appear
more clearly:

@lilypond[quote,verbatim]
\relative {
  d''1-\markup { poco }
  f
  d-\markup { \with-color #darkred \box \hspace #4 poco }
  f
  d-\markup { \with-color #darkred \box \hspace #-4 poco }
  f
  d-\markup { \with-color #darkred \box \hspace #10 poco }
}
@end lilypond

@noindent
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
@ref{Text marks}.

@cindex text, vertical alignment
@cindex vertical alignment, text
@cindex alignment, vertical, text

@funindex \raise
@funindex \lower
@funindex \null

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.

@lilypond[quote,verbatim]
\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
}
@end lilypond

@funindex \general-align
@funindex \translate
@funindex \translate-scaled

Some commands can affect both the horizontal and vertical alignment of
text objects in markup mode:

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

@funindex \vspace
@cindex padding in markup, vertical
@cindex vertical padding in markup

Here again, padding (either positive or negative) is a convenient way
of positioning objects vertically, when inserted into markup columns:

@lilypond[quote,verbatim]
\relative {
  d'2^\markup {
    Acte I
    \column {
      \with-color #darkred \box \vspace #-1
      "Scène 1"
    }
  }
  a'
  g_\markup \column {
    \with-color #darkred \box \vspace #1
    "Très modéré"
  }
  a
  d,^\markup \column {
   "Une forêt."
    \with-color #darkred \box \vspace #2
  }
  a'4 a g2 a
}
@end lilypond

@cindex multi-line markup
@cindex markup, multi-line
@cindex multi-line text
@cindex text, multi-line
@cindex text, in columns
@cindex column, text

@funindex \column
@funindex \center-column

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:

@lilypond[quote,verbatim]
\markup {
  \column {
    a
    "b c"
    \line { d e f }
  }
  \hspace #10
  \center-column {
    a
    "b c"
    \line { d e f }
  }
}
@end lilypond

@cindex centering text on page
@cindex text, centering on page
@cindex markup, centering on page

@funindex \fill-line

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:

@lilypond[quote,verbatim]
\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 }
}
@end lilypond

@cindex text, line width
@cindex markup text, line width

@funindex line-width

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

@lilypond[quote,verbatim]
\markup {
  \column {
    \fill-line { left center right }
    \null
    \override #'(line-width . 30)
    \fill-line { left center right }
  }
}
@end lilypond

@cindex wordwrapped text
@cindex justified text
@cindex text, justified
@cindex text, wordwrapped
@cindex markup text, wordwrapped
@cindex markup text, justified

@funindex \wordwrap
@funindex \justify

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.

@lilypond[quote,verbatim]
\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)
    }
  }
}
@end lilypond

@cindex text alignment command
@cindex markup text, alignment command
@cindex alignment, text, commands

An exhaustive list of text alignment commands can be found in
@ref{Align}.

@morerefs
Learning Manual:
@rlearning{Moving objects}.

Notation Reference:
@ref{Align},
@ref{Text marks}.

Installed Files:
@file{scm/define-markup-commands.scm}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextScript}.
@endmorerefs


@node Graphic notation inside markup
@unnumberedsubsubsec Graphic notation inside markup

@cindex graphics, embedding
@cindex drawing graphic object
@cindex graphic object, drawing
@cindex embedding graphic object
@cindex graphic object, embedding

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

@cindex decorating text
@cindex framing text
@cindex text, framing
@cindex text, decorating
@cindex markup text, decorating
@cindex markup text, framing

@funindex \box
@funindex \circle
@funindex \rounded-box
@c `@funindex \bracket' is auto-generated, too
@funindex \bracket
@funindex \hbracket

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

@lilypond[quote,verbatim]
\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
  }
}
@end lilypond

@cindex padding around text
@cindex text, padding
@cindex markup text, padding

@funindex \pad-markup
@funindex \pad-x
@funindex \pad-to-box
@funindex \pad-around

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

@lilypond[quote,verbatim,line-width=14\cm]
\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."
}
@end lilypond

@cindex graphic notation
@cindex symbol, non-musical
@cindex non-musical symbol
@cindex notation, graphic

@funindex \combine
@funindex \draw-circle
@funindex \filled-box
@funindex \triangle
@funindex \draw-line
@funindex \arrow-head

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

@lilypond[quote,verbatim]
\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
  }
}
@end lilypond

@cindex embedded graphics
@cindex image, embedding
@cindex graphics, embedding
@cindex postscript

@funindex \epsfile
@funindex \postscript

Advanced graphic features include the ability to include external
image files converted to the Encapsulated PostScript format
(@emph{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:

@lilypond[quote,verbatim,fragment]
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'
@end lilypond

An exhaustive list of graphics-specific commands can be found in
@ref{Graphic}.

@morerefs
Notation Reference:
@ref{Align},
@ref{Dimensions},
@ref{Editorial annotations},
@ref{Graphic}.

Installed Files:
@file{scm/define-markup-commands.scm},
@file{scm/stencil.scm}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextScript}.
@endmorerefs


@node Music notation inside markup
@unnumberedsubsubsec Music notation inside markup

@cindex notation, inside markup
@cindex music, inside markup
@cindex markup, music notation inside

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

Notes and accidentals can be entered using markup commands:

@lilypond[quote,verbatim,fragment]
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'
@end lilypond

Other notation objects may also be printed
in markup mode:

@lilypond[quote,verbatim]
\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
  }
}
@end lilypond

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
@ref{The Emmentaler font}.

@lilypond[quote,verbatim]
\relative {
  c''2
  c'^\markup { \musicglyph "eight" }
  c,4
  c,8._\markup { \musicglyph "clefs.G_change" }
  c16
  c2^\markup { \musicglyph "timesig.neomensural94" }
}
@end lilypond

Another way of printing non-text glyphs is described in
@ref{Music fonts}.  This is useful for printing braces of various
sizes.

The markup mode also supports diagrams for specific
instruments:

@lilypond[quote,verbatim]
\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"
  }
}
@end lilypond

@c The accordion diagram is actually taken from a snippet.

@noindent
Such diagrams are documented in @ref{Instrument Specific Markup}.

@cindex score, inside markup
@cindex markup, score inside

A whole score can even be nested inside a markup object:

@lilypond[quote,verbatim]
\relative {
  c'4 d^\markup {
    \score {
      \relative { c'4 d e f }
    }
  }
  e f |
  c d e f
}
@end lilypond

An exhaustive list of music notation related commands can be found in
@ref{Music}.

@morerefs
Notation Reference:
@ref{Music},
@ref{The Emmentaler font},
@ref{Music fonts}.

Installed Files:
@file{scm/define-markup-commands.scm},
@file{scm/fret-diagrams.scm},
@file{scm/harp-pedals.scm}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextScript}.
@endmorerefs

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



@node Fonts
@subsection Fonts

@cindex Pango
@cindex FontConfig

Fonts in LilyPond are handled by several libraries; two of them
are of relevance to the user: @uref{https://fontconfig.org,
@emph{FontConfig}} is used to detect available fonts, and selected
fonts are then rendered by @uref{https://pango.org, @emph{Pango}}
to display text strings.

This section shows how to access fonts in LilyPond, and how to
change them in scores.

@menu
* Finding fonts::
* Font families::
* Font features::
* Single entry fonts::
* Entire document fonts::
* Music fonts::
@end menu

@node Finding fonts
@unnumberedsubsubsec Finding fonts

@cindex font, finding
@cindex font, external files

In addition to any font already installed on the operating system,
more fonts may be added to the ones detected by FontConfig (and
thus available in LilyPond scores) by the following commands:

@example
#(ly:font-config-add-font "@var{path/to/font-file}")
#(ly:font-config-add-directory "@var{path/to/directory/}")
@end example

@noindent
Both commands accept either absolute or relative paths, which
makes it possible to compile a score on any system by simply
distributing the relevant font files together with the LilyPond
input files.

To verify that the desired fonts are found by FontConfig, use the
command @code{#(ly:font-config-display-fonts)}, which prints the
complete list of available fonts to the console log.  It also
shows the actual font names to be used with LilyPond; these may
differ from the file names themselves.

@xref{Single entry fonts} and @ref{Entire document fonts} how to
access fonts in general.


@node Font families
@unnumberedsubsubsec Font families

Three generic aliases for text font families@footnote{In its
simplest form, a @emph{font family} usually contains fonts in
roman, italic, bold, and bold italic styles.} are available:
@q{roman} (serif), @q{sans}, and @q{typewriter}.  Depending on the
backend, these families get mapped to different font family
aliases.

For the @code{svg} backend:

@indentedBlock
@multitable {@b{generic family}} {@b{SVG font family}}
@headitem generic family @tab SVG font family
@item roman @tab serif
@item sans @tab sans-serif
@item typewriter @tab monospace
@end multitable
@endIndentedBlock

@noindent
@q{serif}, @q{sans-serif}, and @q{monospace} are
@q{generic-family} in SVG and CSS specifications.

For other backends:

@indentedBlock
@multitable @columnfractions .17 .30 .45
@headitem generic family
          @tab default font family alias
                    @tab font families contained in alias
@item roman
@tab LilyPond Serif
@tab C059,
     Century SchoolBook URW,
     Century Schoolbook@tie{}L,
     TeX Gyre Schola,
     DejaVu Serif,
     @dots{},
     serif
@item sans
@tab LilyPond Sans Serif
@tab Nimbus Sans,
     Nimbus Sans@tie{}L,
     TeX Gyre Heros,
     DejaVu Sans,
     @dots{},
     sans-serif
@item typewriter
@tab LilyPond Monospace
@tab Nimbus Mono PS,
     Nimbus Mono,
     Nimbus Mono@tie{}L,
     TeX Gyre Cursor,
     DejaVu Sans Mono,
     @dots{},
     monospace
@end multitable
@endIndentedBlock

@noindent
If a character does not exist in the appropriate font of the first
listed family, the appropriate font of the next listed family gets
used instead for that character.

Note that the URW font families distributed with LilyPond
(@q{C059}, @q{Nimbus Sans}, and @q{Nimbus Mono PS}) have a
peculiarity: By default, in addition to the standard ligatures
like @q{fl} or @q{ffi}, they substitute the string @q{Nr.} with
the Numero Sign (U+2116) if the @q{latn} script is selected.  To
circumvent this locally, insert a @emph{zero-width non-joiner
character} (ZWNJ, U+200C) between the @q{N} and @q{r} characters.
To circumvent this globally, use the following code to make
LilyPond always insert a ZWNJ character.

@example
\paper @{
  #(add-text-replacements!
      `(("Nr." . ,(format #f "N~ar." (ly:wide-char->utf-8 #x200C)))))
@}
@end example

@q{LilyPond Serif}, @q{LilyPond Sans Serif}, and @q{LilyPond
Monospace} are font family aliases defined in the additional
FontConfig configuration file @file{00-lilypond-fonts.conf}, which
can be usually found in directory
@file{/usr/local/share/lilypond/@version{}/fonts}, and which is
used exclusively by LilyPond.

Each font family may include different shapes and series.  The
following example demonstrates that, including code to also change
the size.  The value supplied to @code{font-size} is taken
relative to the default font size.

@lilypond[quote,verbatim,fragment]
\override Score.TextMark.font-family = #'typewriter
\textMark "Ouverture"
\override Voice.TextScript.font-shape = #'italic
\override Voice.TextScript.font-series = #'bold
d''2.^\markup "Allegro"
\override Voice.TextScript.font-size = #-3
c''4^"smaller"
@end lilypond

@noindent
A similar syntax may be used in markup mode; however, in most
cases it is preferable to use the simpler syntax explained in
@ref{Selecting font and font size}:

@lilypond[quote,verbatim]
\markup {
  \column {
    \line {
      \override #'((font-shape . italic) (font-size . 4))
      Idomeneo,
    }
    \line {
      \override #'(font-family . typewriter) {
        \override #'(font-series . bold) re
        di
      }
      \override #'(font-family . sans) Creta
    }
  }
}
@end lilypond


@node Font features
@unnumberedsubsubsec Font features

@cindex feature, OpenType font
@cindex font feature, OpenType
@cindex OpenType, font feature

When using OpenType fonts, font features can be
used.@footnote{Selecting OpenType font scripts and languages is
not supported yet.}  Note that not all OpenType fonts have all
features.  If you request a feature that does not exist in the
chosen font, the feature is simply ignored.  The example below
uses the font @q{TeX Gyre Schola} (this is, the roman style of the
family).

@lilypond[quote,verbatim]
\markup { \override #'(font-name . "TeX Gyre Schola")
          normal style: Hello HELLO }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \caps { small caps: Hello } }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("smcp"))
          { true small caps: Hello } }

\markup { \override #'(font-name . "TeX Gyre Schola")
          normal number style: 0123456789 }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("onum"))
          { old number style: 0123456789 } }

\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("salt 0"))
          { stylistic alternate 0: εφπρθ } }
\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("salt 1"))
          { stylistic alternate 1: εφπρθ } }

\markup { \override #'(font-name . "TeX Gyre Schola")
          \override #'(font-features . ("onum" "smcp" "salt 1"))
          { multiple features: Hello 0123456789 εφπρθ } }
@end lilypond

For the full OpenType font feature list see
@uref{https://www.microsoft.com/typography/otspec/featurelist.htm};
for identifying features of OpenType fonts see
@uref{https://lists.gnu.org/archive/html/lilypond-devel/2017-08/msg00004.html}.

Although it is easy to switch between preconfigured fonts, it is
also possible to use other fonts.  For more information,
@pxref{Single entry fonts} and @ref{Entire document fonts}.

@morerefs
Notation Reference:
@ref{The Emmentaler font},
@ref{Music notation inside markup},
@ref{Rotating objects},
@ref{Selecting font and font size},
@ref{Font}.
@endmorerefs


@node Single entry fonts
@unnumberedsubsubsec Single entry fonts

Almost all outline fonts installed on the operating system and
recognized by FontConfig may be used in a score, with the
exception of bitmap fonts (which are not supported by design) and
OpenType Variation Fonts (which are not supported yet).

LilyPond calls function @code{pango_font_description_from_string}
from the Pango library to access fonts; it uses the following
syntax form for font names.@footnote{The data is taken from the
Pango reference for version 1.46.1; the syntax supported by
LilyPond is actually a subset of what Pango provides.}

@example
[@var{family-list}] [@var{style-options}]
@end example

@noindent
where @var{family-list} is a comma-separated list of families
optionally terminated by a comma, and @var{style-options} a
whitespace-separated list of words where each word describes one
of style, variant, weight, stretch, or gravity.

The following words are understood as styles: @code{Normal} (the
default), @code{Roman}, @code{Oblique}, @code{Italic}.

The following words are understood as variants:
@code{Small-Caps}.  Default is no variant.

The following words are understood as weights: @code{Thin},
@code{Ultra-Light}, @code{Extra-Light}, @code{Light},
@code{Semi-Light}, @code{Demi-Light}, @code{Book}, @code{Regular}
(the default), @code{Medium}, @code{Semi-Bold}, @code{Demi-Bold},
@code{Bold}, @code{Ultra-Bold}, @code{Extra-Bold}, @code{Heavy},
@code{Black}, @code{Ultra-Black}, @code{Extra-Black}.

The following words are understood as stretch values:
@code{Ultra-Condensed}, @code{Extra-Condensed}, @code{Condensed},
@code{Semi-Condensed}, @code{Semi-Expanded}, @code{Expanded},
@code{Extra-Expanded}, @code{Ultra-Expanded}.  Default is no
stretch.

The following words are understood as gravity values:
@code{Not-Rotated}, @code{South}, @code{Upside-Down},
@code{North}, @code{Rotated-Left}, @code{East},
@code{Rotated-Right}, @code{West}.  Default is no gravity.

Assuming the syntax is correct, setting a font name never fails.
If none of the font families are known (or no font family is
given), FontConfig returns a default font depending on the
operating system.  If none of the style options are known (or no
style option is given), default values are used.

In the following example, the font for the time signature is set
to @q{Bitstream Charter}.  Since no style option is given,
FontConfig uses default values as specified above.  For the markup
string, the list of font families is set to @q{Bitstream Vera
Sans} and @q{sans-serif}, which tells FontConfig to try
@q{Bitstream Vera Sans} first; if it is not available, it tries
the generic font family @q{sans-serif} as described in @ref{Font
families}.  The style for the markup is set to @q{Oblique Bold},
which makes FontConfig try to find a font that is both oblique and
bold.  If that fails, it tries to find an oblique or bold font.
If that fails again, it tries to match a font with default style
options.

Note that FontConfig also checks whether the requested glyph is
actually present in the font.  In case it is missing, another font
gets tried (following the above algorithm) until the glyph is
eventually found.  Only if FontConfig fails to find any font with
the appropriate glyph a symbol for a missing glyph is shown (which
is normally a rectangular box or simply some whitespace).

@lilypond[quote,verbatim,fragment]
\override Staff.TimeSignature.font-name = "Bitstream Charter"
\override Staff.TimeSignature.font-size = #2
\time 3/4

a'1_\markup {
  \override #'(font-name .
               "Bitstream Vera Sans, sans-serif, Oblique Bold")
    { Vera Oblique Bold }
}
@end lilypond

@warning{If any of the above style options is part of the font
(family) name you @emph{must} use a trailing comma after the name
even if you do not select a style option.  A typical example is
@q{Times New Roman}: If specified as @code{"Times New Roman"},
FontConfig searches for a font @q{Times New} in roman style.  Only
if you say @code{"Times New Roman,"} this font is really
accessed.}

@cindex font, finding available
@cindex finding available fonts
@cindex listing available fonts
@cindex available fonts, listing
@funindex show-available-fonts

Running @command{lilypond} on the command line with the following
option displays a list of all available fonts on the operating
system:

@example
lilypond -dshow-available-fonts
@end example

@morerefs
Notation Reference:
@ref{Finding fonts},
@ref{Font families},
@ref{Entire document fonts}.

Snippets:
@rlsr{Text}.
@endmorerefs

@c A source file gets never installed...
@c Installed Files:
@c @file{lily/font-config-scheme.cc}.


@node Entire document fonts
@unnumberedsubsubsec Entire document fonts

It is possible to change the fonts used in LilyPond's default font
families by calling the function @code{make-pango-font-tree}.  The
arguments are substitutions for the @q{roman}, @q{sans} and
@q{typewriter} font families (in that order), followed by a
scaling factor.  Similar to single fonts (@pxref{Single entry
fonts}), font families are set up by using comma-separated lists
of font family names, but without style options.@footnote{This
implies that, contrary to single fonts, a trailing comma is never
necessary.}

Note that @code{make-pango-font-tree} resets the notation fonts to
@q{emmentaler} as the default.

The example below adjusts the font size in relation to the global
staff size.

@cindex font family, setting
@cindex font, changing for entire document
@funindex make-pango-font-tree

@lilypond[verbatim,quote]
\paper {
  #(define fonts
    (make-pango-font-tree "Linux Libertine O"
                          "Nimbus Sans, Nimbus Sans L"
                          "DejaVu Sans Mono"
                          (/ staff-height pt 20)))
}

\relative c'{
  c1-\markup {
    roman,
    \sans sans,
    \typewriter typewriter. }
}
@end lilypond

LilyPond provides an alternative, more flexible interface to set
global font families.  It allows you to change only specific font
family names, leaving others set to default values.  The following
example has the same effect as the above
@code{make-pango-font-tree} example; the syntax for font family
names is identical.  If you do not change the staff size from the
default of 20@dmn{pt}, the line containing the @code{#:factor}
keyword is unnecessary.

@funindex set-global-fonts

@example
\paper @{
  #(define fonts
    (set-global-fonts
     #:roman "Linux Libertine O"
     #:sans "Nimbus Sans, Nimbus Sans L"
     #:typewriter "DejaVu Sans Mono"
     ; unnecessary if the staff size is default
     #:factor (/ staff-height pt 20)
    ))
@}
@end example

Additionally, @code{set-global-fonts} can also set the music
notation fonts.  The following example has the same effect as the
previous examples, because it uses the default notation fonts.
For more information, see @ref{Replacing the notation font}.

@example
\paper @{
  #(define fonts
    (set-global-fonts
     #:music "emmentaler"            ; default
     #:brace "emmentaler"            ; default
     #:roman "Linux Libertine O"
     #:sans "Nimbus Sans, Nimbus Sans L"
     #:typewriter "DejaVu Sans Mono"
     ; unnecessary if the staff size is default
     #:factor (/ staff-height pt 20)
    ))
@}
@end example

Note that each call to @code{set-global-fonts} completely resets
both the main notation and text fonts.@footnote{To be more
precise, @q{emmentaler} (with a lowercase @q{e}, which is
mandatory in the argument to @code{#:music} and @code{#:brace}) is
a set of fonts (but not a font family in the FontConfig sense)
that LilyPond accesses and manages directly.  Instead of various
styles, however, it comes with different design sizes,
@pxref{Music fonts} and @ref{Replacing the notation font}.  The
corresponding FontConfig font names are @q{Emmentaler-@var{size}},
where @var{size} is one of the numbers 11, 13, 14, 16, 18, 20, 23,
and@tie{}26.

For braces, the FontConfig font name is @q{Emmentaler-Brace}.}  If
any font category is left unspecified, the respective default font
(family) gets used for that category.  Each call of
@code{set-global-fonts} affects all @code{\book} blocks that
follow it.  If there are multiple @code{\book} blocks and you want
to use different fonts for each, simply call
@code{set-global-fonts} again, like this:

@example
\paper @{
  #(define fonts
    (set-global-fonts
     @dots{}
    ))
@}
\book @{
  @dots{}
@}

\paper @{
  #(define fonts
    (set-global-fonts
     @dots{}
    ))
@}
\book @{
  @dots{}
@}
@end example

@morerefs
Notation Reference:
@ref{Finding fonts},
@ref{Font families},
@ref{Single entry fonts},
@ref{Selecting font and font size},
@ref{Font},
@ref{Replacing the notation font}.
@endmorerefs


@node Music fonts
@unnumberedsubsubsec Music fonts

@cindex font, music notation
@funindex font-encoding
@funindex font-interface

LilyPond neither uses FontConfig nor Pango for accessing music
notation fonts but handles them by itself.  As a consequence, the
interface is different.  This section describes how to insert
music symbols into markup strings.

@cindex brace, various sizes
@cindex font, non-text in markup
@cindex non-text font, in markup

Music notation fonts are a collection of specific glyphs that can
be accessed with several @emph{encodings}.  The following syntax
allows LilyPond's various Emmentaler glyphs@footnote{LilyPond's
Emmentaler fonts contain three glyph sets: @emph{Feta} (for modern
notation), @emph{Parmesan} (for ancient notation), and braces.
Both Feta and Parmesan are accessed with the @q{fetaMusic}
encoding.} to be used directly in markup mode:

@lilypond[quote,verbatim,fragment]
a'1^\markup {
  \vcenter {
    \override #'(font-encoding . fetaBraces)
    \lookup "brace120"
    \override #'(font-encoding . fetaText)
    \column { 1 3 sf }
    \override #'(font-encoding . fetaMusic)
    \lookup "noteheads.s0petrucci"
  }
}
@end lilypond

@noindent
However, all these glyphs except the braces of various sizes are
available using the simpler syntax described in @ref{Music
notation inside markup}.

When accessing braces with the @q{fetaBraces} encoding, the size
of the brace is specified by the numerical part of the glyph name,
in arbitrary units.  Any integer from 0 to 575 inclusive may be
specified, with 0 giving the smallest brace.  The optimum value
must be determined by trial and error.  These glyphs are all left
braces; right braces may be obtained by rotation, @pxref{Rotating
objects}.
