Docs: reorganize documentation directory structure

[lilypond.git] / Documentation / notation / text.itely

@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.  See TRANSLATION for details.
@end ignore

@c \version "2.12.0"

@node Text
@section Text

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

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

@noindent
Some text elements that are not dealt with here are discussed in other
specific sections: @ref{Vocal music}, @ref{Titles and headers}.

@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 scripts::
* Text spanners::
* Text marks::
* Separate text::
@end menu


@node Text scripts
@unnumberedsubsubsec Text scripts

@cindex Text scripts
@cindex text items, non-empty
@cindex non-empty texts
@cindex quoted text

Simple @qq{quoted text} indications may be added to a score.

@lilypond[quote,verbatim,relative=2]
a8^"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=2]
a8^\markup { \italic pizz. } g f e
a4_\markup { \tiny scherz. \bold molto } f
@end lilypond

@qq{Quoted text} and @code{\markup} commands may be manually
placed above or below the staff; see @ref{Direction and
placement}.

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=2]
a8^"pizz." g f e
\textLengthOn
a4_"scherzando" f
@end lilypond


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


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

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextScript}.


@knownissues

Checking to make sure that text scripts and lyrics are within the
margins is a relatively large computational task.  To speed up
processing, LilyPond does not perform such calculations by
default; to enable it, use

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


@node Text spanners
@unnumberedsubsubsec Text spanners

@cindex Text spanners

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=2]
\override TextSpanner #'(bound-details left text) = "rit."
b1\startTextSpan
e,\stopTextSpan
@end lilypond

@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,relative=2,verbatim]
\override TextSpanner #'(bound-details left text) =
  \markup { \upright "rit." }
b1\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}.

Text spanners may be manually placed above or below the staff; see
@ref{Direction and placement}.


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


@seealso
Notation Reference:
@ref{Line styles},
@ref{Dynamics},
@ref{Direction and placement}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextSpanner}.


@node Text marks
@unnumberedsubsubsec Text marks

@cindex coda on bar line
@cindex segno on bar line
@cindex fermata on bar line
@cindex bar lines, symbols on
@funindex \mark

Various text elements may be added to a score using
the syntax described in @ref{Rehearsal marks}:

@c \mark needs to be placed on a separate line (it's not
@c attached to an object like \markup is). -vv

@lilypond[verbatim,quote,relative=2]
c4
\mark "Allegro"
c c c
@end lilypond

This syntax makes it possible to put any text on a bar line;
more complex text formatting may be added using a @code{\markup}
block, as described in @ref{Formatting text}:

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

@noindent
This syntax also allows to print special signs, like coda, segno
or fermata, by specifying the appropriate symbol name as explained in
@ref{Music notation inside markup}:

@lilypond[quote,verbatim,relative=2]
<bes f>2 <aes d>
\mark \markup { \musicglyph #"scripts.ufermata" }
<e g>1
@end lilypond

@noindent
Such objects are only typeset above the top staff of the score; depending on
whether they are specified at the end or the middle of a bar, they
can be placed above the bar line or between notes.  When specified at a
line break, the mark will be printed at the beginning of the next line.

@lilypond[quote,verbatim,relative=2]
\mark "Allegro"
c1 c
\mark "assai" \break
c  c
@end lilypond


@snippets

@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
{printing-marks-at-the-end-of-a-line-or-a-score.ly}

@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
{aligning-marks-with-various-notation-objects.ly}

@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
{printing-marks-on-every-staff.ly}


@seealso
Notation Reference:
@ref{Rehearsal marks},
@ref{Formatting text},
@ref{Music notation inside markup},
@ref{The Feta font}.

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{RehearsalMark}.


@knownissues
@c  To be removed when Issue 69 in the tracker gets fixed. -vv

If a mark is entered at the end of the last bar of the score (where
there is no next line), then the mark will not be printed at
all.

@node Separate text
@unnumberedsubsubsec Separate text

@cindex separate text
@cindex standalone text
@cindex top-level text
@cindex text, standalone
@funindex \markup

A @code{\markup} block can exist by itself, outside of any
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

Separate text blocks can be spread over multiple pages,
making it possible to print text documents or books entirely
within LilyPond.  This feature, and the specific syntax it
requires, are described in @ref{Multi-page markup}.


@predefined
@funindex \markuplines
@code{\markup},
@code{\markuplines}.
@endpredefined


@snippets

@lilypondfile[verbatim,lilyquote,ragged-right,texidoc,doctitle]
{stand-alone-two-column-markup.ly}

@seealso
Notation Reference: @ref{Formatting text},
@ref{File structure},
@ref{Multiple scores in a book},
@ref{Multi-page markup}.

Snippets:
@rlsr{Text}.

Internals Reference: @rinternals{TextScript}.


@node Formatting text
@subsection Formatting text

This section presents basic and advanced text formatting,
using the @code{\markup} mode specific syntax.

@menu
* Text markup introduction::
* Selecting font and font size::
* Text alignment::
* Graphic notation inside markup::
* Music notation inside markup::
* Multi-page 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} block is used to typeset text with an extensible
syntax called @qq{markup mode}.

@cindex markup expressions
@cindex markup syntax

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

Unlike simple @qq{quoted text} indications, @code{\markup} blocks
may contain nested expressions or markup commands,
entered using the backslash @code{\} character.
Such commands only affect the first following expression.

@lilypond[quote,verbatim,relative=2]
a1-\markup intenso
a2^\markup { poco \italic più forte  }
c e1
d2_\markup { \italic "string. assai" }
e
b1^\markup { \bold { molto \italic  agitato } }
c
@end lilypond

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

A @code{\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
@code{\} and @code{#}) will be printed verbatim without affecting
the formatting of the text.  Double quotation marks themselves
may be printed by preceding them with backslashes.

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

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 @code{\markup} expression is
treated the same as the first one:

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

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

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

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


@noindent
An exhaustive list of @code{\markup}-specific commands can be found in
@ref{Text markup commands}.


@seealso
Notation Reference:
@ref{Text markup commands}.

Snippets:
@rlsr{Text}.

Installed files:
@file{scm/@/markup@/.scm}.


@knownissues

Syntax errors for markup mode can be confusing.


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

@cindex font switching
@funindex \italic
@funindex \bold
@funindex \underline

Basic font switching is supported in markup mode:

@lilypond[quote,verbatim,relative=2]
d1^\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 \fontsize
@funindex \smaller
@funindex \larger
@funindex \magnify

The size of the characters can also be altered in different ways:
@itemize
@item
the font size can be set to predefined standard sizes,

@item
the font size can be set to an absolute value,

@item
the font size can also be changed relatively to its previous value.
@end itemize

@noindent
The following example demonstrates these three methods:

@lilypond[quote,verbatim,relative=1]
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
@end lilypond

@cindex subscript
@cindex superscript
@funindex \super
@funindex \sub

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 families

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, and custom font usage
commands can be found in @ref{Font}.

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


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


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

Snippets:
@rlsr{Text}.

Internals Reference:
@rinternals{TextScript}.

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


@node Text alignment
@unnumberedsubsubsec Text alignment

@cindex text, aligning
@cindex aligning text

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}.

@c Padding commands should be mentioned on this page, but
@c most of these require \box to be more clearly illustrated. -vv

@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.

@lilypond[quote,verbatim,relative=2]
d1-\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=2]
a1-\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

@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 text alignment
@funindex \raise
@funindex \lower

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 @emph{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.

@lilypond[quote,verbatim,relative=1]
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
@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.  Any object
affected by these commands must be preceded with an
anchor point:

@lilypond[quote,verbatim,relative=1]
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
@end lilypond

@funindex \column
@funindex \center-column

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

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

@funindex \fill-line

@cindex centering text on the page

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

@funindex \wordwrap
@funindex \justify

@cindex wordwrapped text
@cindex justified text

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

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


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

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

Snippets:
@rlsr{Text}.

Internals Reference: @rinternals{TextScript}.

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


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

@cindex graphics, embedding
@cindex drawing graphic objects

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

@funindex \box
@funindex \circle
@funindex \rounded-box
@funindex \bracket
@funindex \hbracket

@cindex decorating text
@cindex framing text

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

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

@cindex padding around text
@cindex text padding

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]
\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."
}
@end lilypond

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

@cindex graphic notation
@cindex symbols, non-musical

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

@funindex \epsfile
@funindex \postscript

@cindex embedded graphics
@cindex images, embedding
@cindex graphics, embedding
@cindex 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,relative=1]
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
@end lilypond

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


@seealso
Notation Reference:
@ref{Graphic},
@ref{Editorial annotations}.

Snippets:
@rlsr{Text}.

Internals Reference: @rinternals{TextScript}.

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


@node Music notation inside markup
@unnumberedsubsubsec 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:

@lilypond[quote,verbatim,relative=2]
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
@end lilypond

Other notation objects may also be printed
in markup mode:

@lilypond[quote,verbatim,relative=1]
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
}
@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 Feta font}.

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

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

The markup mode also supports diagrams for specific
instruments:

@lilypond[quote,verbatim,relative=2]
c1^\markup {
  \fret-diagram-terse #"x;x;o;2;3;2;"
}
c^\markup {
  \harp-pedal #"^-v|--ov^"
}
c
c^\markup {
  \combine
    \musicglyph #"accordion.accDiscant"
    \combine
      \raise #0.5 \musicglyph #"accordion.accDot"
      \raise #1.5 \musicglyph #"accordion.accDot"
}
@end lilypond

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

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

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

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

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


@seealso
Notation Reference:
@ref{Music},
@ref{The Feta font},
@ref{Fonts explained}.

Snippets:
@rlsr{Text}.

Internals Reference: @rinternals{TextScript}.

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


@node Multi-page markup
@unnumberedsubsubsec 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:

@lilypond[quote,verbatim]
\markuplines {
  \justified-lines {
    A very long text of justified lines.
    ...
  }
  \wordwrap-lines {
    Another very long paragraph.
    ...
  }
  ...
}
@end lilypond

This syntax accepts a list of markups, that can be
@itemize
@item
the result of a markup list command,
@item
a list of markups,
@item
a list of markup lists.
@end itemize

An exhaustive list of markup list commands can be found in
@ref{Text markup list commands}.


@seealso
Notation Reference:
@ref{Text markup list commands},
@ref{New markup list command definition}.

Snippets:
@rlsr{Text}.

Internals Reference: @rinternals{TextScript}.

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


@predefined
@funindex \markuplines
@code{\markuplines}.
@endpredefined


@node Fonts
@subsection Fonts

This section presents the way fonts are handled,
and how they may be changed in scores.

@menu
* Fonts explained::
* Single entry fonts::
* Entire document fonts::
@end menu

@node Fonts explained
@unnumberedsubsubsec Fonts explained

@cindex Pango
@cindex fonts, explained
@cindex braces, various sizes
@funindex font-interface

Fonts are handled through several libraries.
FontConfig is used to detect available fonts on the system;
the selected fonts are rendered using Pango.

Music notation fonts can be described as a set of
specific glyphs, ordered in several families.
The following syntax allows various LilyPond @code{feta} non-text
fonts to be used directly in markup mode:

@lilypond[quote,verbatim,relative=2]
a1^\markup {
  \vcenter {
    \override #'(font-encoding . fetaBraces)
    \lookup #"brace120"
    \override #'(font-encoding . fetaNumber)
    \column { 1 3 }
    \override #'(font-encoding . fetaDynamic)
    sf
    \override #'(font-encoding . fetaMusic)
    \lookup #"noteheads.s0petrucci"
  }
}
@end lilypond

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

When using the glyphs contained in @code{fetaBraces}, the size of
the brace is specified by the numerical part of the glyph name, in
arbitrary units.  Any integer from @code{0} to @code{575} inclusive
may be specified, @code{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, see
@ref{Rotating objects}.

Three families of text fonts are made available: the
@emph{roman} (serif) font, that defaults to New Century
Schoolbook, the @emph{sans} font and the monospaced
@emph{typewriter} font -- these last two families are
determined by the Pango installation.

Each family may include different shapes and series.
The following example demonstrates the ability to select
alternate families, shapes, series and sizes.  The value
supplied to @code{font-size} is the required change from the
default size.

@lilypond[quote,verbatim,relative=2]
\override Score.RehearsalMark #'font-family = #'typewriter
\mark \markup "Ouverture"
\override Voice.TextScript #'font-shape = #'italic
\override Voice.TextScript #'font-series = #'bold
d2.^\markup "Allegro"
\override Voice.TextScript #'font-size = #-3
c4^smaller
@end lilypond

@noindent
A similar syntax may be used in markup mode, however in this case
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)
      \override #'(font-size . 4)
      Idomeneo,
    }
    \line {
      \override #'(font-family . typewriter)
      {
        \override #'(font-series . bold)
        re
        di
      }
      \override #'(font-family . sans)
      Creta
    }
  }
}
@end lilypond

Although it is easy to switch between preconfigured fonts,
it is also possible to use other fonts, as explained in the
following sections: @ref{Single entry fonts} and
@ref{Entire document fonts}.


@seealso
Notation Reference:
@ref{The Feta font},
@ref{Music notation inside markup},
@ref{Selecting font and font size},
@ref{Font}.


@node Single entry fonts
@unnumberedsubsubsec Single entry fonts

Any font that is installed on the operating system and recognized
by FontConfig may be used in a score, using the following syntax:

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

a1_\markup {
  \override #'(font-name . "Vera Bold")
    { Vera Bold }
}
@end lilypond

@funindex show-available-fonts

The following command displays a list of all available fonts
on the operating system:

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

@noindent
The last argument of the command can be anything, but has to be
present.


@seealso
Notation Reference:
@ref{Fonts explained},
@ref{Entire document fonts}.

Snippets:
@rlsr{Text}.

Installed files:
@file{lily/@/font@/-config@/-scheme@/.cc}.


@node Entire document fonts
@unnumberedsubsubsec Entire document fonts

It is possible to change the fonts to be used as the default fonts in
the @emph{roman}, @emph{sans} and @emph{typewriter} font families by
specifying them, in that order, as shown in the example below.  For an
explanation of fonts, see @ref{Fonts explained}.

@cindex font families, setting
@funindex make-pango-font-tree

@lilypond[verbatim,quote]
\paper  {
  myStaffSize = #20
  #(define fonts
    (make-pango-font-tree "Times New Roman"
                          "Nimbus Sans"
                          "Luxi Mono"
                           (/ myStaffSize 20)))
}

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

@c we don't do Helvetica / Courier, since GS incorrectly loads
@c Apple TTF fonts


@seealso
Notation Reference:
@ref{Fonts explained},
@ref{Single entry fonts},
@ref{Selecting font and font size},
@ref{Font}.