Backslash macro

[lilypond.git] / Documentation / user / 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

@node Text
@section Text

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

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

@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
* Writing text::                
* Text markup::                 
* Special text concerns::       
@end menu


@node Writing text
@subsection Writing text

@menu
* Overview of text entry::      
* Text scripts::                
* Text spanners::               
* Text marks::                  
@end menu

@node Overview of text entry
@subsubsection Overview of text entry

There are four ways to add text to scores:

@itemize
@item
@ref{Text scripts}: blah blah

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c4^"text" c c c
@end lilypond

@item
@ref{Text spanners}: blah blah

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c1
\override TextSpanner #'bound-details #'left #'text =
  \markup { \upright "rall" } 
c2\startTextSpan b c\stopTextSpan a
@end lilypond

@item
@ref{Text marks}: blah blah

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c4\mark "foo" c c c
@end lilypond

@item
@ref{Vocal music}: blah blah, not in this section.

@lilypond[verbatim,quote,ragged-right]
<<
  \relative c'' { c4 c c c }
  \addlyrics { one two three four }
>>
@end lilypond

@end itemize

@seealso

Snippets: @lsrdir{Text,Text}



@node Text scripts
@subsubsection Text scripts

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

It is possible to add arbitrary text indications with
@var{note}@code{-"}@var{text}@code{"}.
Such indications can also be manually placed
above or below the staff, using the
simple syntax described in @ref{Controlling direction and
placement}.

@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
d8^"pizz." e f g a4-"scherz." f
@end lilypond

In LilyPond, such text strings are called @command{markup}
objects.  This syntax is actually a shorthand; more complex text
formatting may be added to a note by explicitly using the
@code{\markup} command, as described in @ref{Text markup}.

@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
d8^\markup { \italic pizz. } e f g 
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,fragment,ragged-right,verbatim,relative=1]
d8^"pizz." e f g \textLengthOn a4_"scherzando" f
@end lilypond

@predefined

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


@seealso

Notation Reference: @ref{Text markup}.

Snippets: @lsrdir{Text,Text}

Internals Reference: @internalsref{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
@subsubsection Text spanners

@cindex Text spanners

@c TODO: merge these explanations with the ones below in 
@c "Text and Line spanners" -vv

Some performance indications, e.g., @i{rallentando} or
@i{accelerando}, are written as text and are extended over many
measures with dotted lines; you can create such text spanners
from one note to another by using the following syntax:

@lilypond[verbatim,quote,ragged-right,fragment,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:

@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
\override TextSpanner #'bound-details #'left #'text =
  \markup { \upright "rit." } 
b1\startTextSpan c
e,\stopTextSpan
@end lilypond

@predefined

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

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


@seealso

Snippets: @lsrdir{Text,Text}

Internals Reference: @internalsref{TextSpanner}.


@node Text marks
@subsubsection 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 can be added to a score using
the syntax described in @ref{Rehearsal marks}:

@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
c4\mark "dolce" c c c
@end lilypond

This syntax makes possible to put any text on a bar line, but also
signs like coda, segno, or fermata, by specifying  the appropriate
symbol name.  These symbols are listed in @ref{The Feta font}.

@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
c1 \mark \markup { \musicglyph #"scripts.ufermata" }
c1
@end lilypond

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

@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
\mark "dolce" c1
c\mark "assai" \break
c c
@end lilypond


@snippets

@c TODO: to be LSR-ized stuff -vv

To print the mark at the end of the current line, use

@example
\override Score.RehearsalMark
  #'break-visibility = #begin-of-line-invisible
@end example

@code{\mark} is often useful for adding text to the end of bar.
In such cases, changing the @code{#'self-alignment} is very useful

@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
\override Score.RehearsalMark
  #'break-visibility = #begin-of-line-invisible
c1 c c c4 c c c
\once \override Score.RehearsalMark #'self-alignment-X = #right
\mark "D.S. al Fine "
@end lilypond

Text marks may be aligned with notation objects other than bar
lines,

@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
\relative {
  c1
  \key cis \major
  \clef alto
  \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
  \mark "on key"
  cis
  \key ces \major
  \override Score.RehearsalMark #'break-align-symbols = #'(clef)
  \clef treble
  \mark "on clef"
  ces
  \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
  \key d \minor
  \clef tenor
  \time 3/4
  \mark "on time"
  c
}
@end lilypond

Possible symbols for the @code{break-align-symbols} list are
@code{ambitus}, @code{breathing-sign}, @code{clef}, @code{custos},
@code{staff-bar}, @code{left-edge}, @code{key-cancellation},
@code{key-signature}, and @code{time-signature}.

The text marks will, by default, be aligned with the middle of the
notation object, but this can be changed by overriding the
@code{break-align-anchor-alignment} and @code{break-align-anchor}
properties for the appropriate grob. For scores with multiple staves,
this setting should be done for all the staves. 

@lilypond[fragment,quote,ragged-right,verbatim]
{
  \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
  c1
  \key cis \major

  % the RehearsalMark will be aligned with the left edge of the KeySignature
  \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
  \mark \default
  cis1
  \key ces \major

  % the RehearsalMark will be aligned with the right edge of the KeySignature
  \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
  \mark \default
  ces1
  \key cis \major

  % the RehearsalMark will be aligned with the left edge of the KeySignature
  % and then shifted right by 2 units.
  \once \override Score.KeySignature #'break-align-anchor = #2
  \mark \default
  ces1
}
@end lilypond

Although text marks are normally only printed above the topmost
staff, you may alter this to print them on every staff,

@lilypond[quote,ragged-right,verbatim,relative=2]
{
  \new Score \with {
    \remove "Mark_engraver"
  }
  <<
    \new Staff \with {
      \consists "Mark_engraver"
    }
    { c''1 \mark "foo" c'' }
    \new Staff \with {
      \consists "Mark_engraver"
    }
    { c'1 \mark "foo" c' }
  >>
}
@end lilypond


@seealso

Snippets: @lsrdir{Text,Text}

Internals Reference: @internalsref{RehearsalMark}.

@knownissues
@c  IMO this is a bug; hopefully it'll be fixed soon, so I can
@c  delete this sentence.   -gp

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.

@c TODO: add this here? -vv
@c @node Text marks
@c @subsubsection Text marks

@node Text markup
@subsection Text markup

@menu
* Text markup introduction::    
* Nested scores::               
* Page wrapping text::          
* Font selection::              
@end menu

@node Text markup introduction
@subsubsection Text markup introduction

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

Use @code{\markup} to typeset text.  Commands are entered with the
backslash @code{\}.  To enter @code{\} and @code{#}, use double
quotation marks.

@lilypond[quote,verbatim,fragment,relative=1]
c1^\markup { hello }
c1_\markup { hi there }
c1^\markup { hi \bold there, is \italic {anyone home?} }
c1_\markup { "\special {weird} #characters" }
@end lilypond

@noindent
See @ref{Overview of text markup commands}, for a list of all
commands.

@code{\markup} is primarily used for @internalsref{TextScript}s,
but it can also be used anywhere text is called in lilypond

@lilypond[quote,verbatim]
\header{ title = \markup{ \bold { foo \italic { bar! } } } }
\score{
  \relative c'' {
    \override Score.RehearsalMark
      #'break-visibility = #begin-of-line-invisible
    \override Score.RehearsalMark #'self-alignment-X = #right

    \set Staff.instrumentName = \markup{ \column{ Alto solo } }
    c2^\markup{ don't be \flat }
    \override TextSpanner #'bound-details #'left #'text = \markup{\italic rit }
    b2\startTextSpan
    a2\mark \markup{ \large \bold Fine }
    r2\stopTextSpan
    \bar "||"
  }
  \addlyrics { bar, foo \markup{ \italic bar! } }
}
@end lilypond

A @code{\markup} command can also be placed on its own, away from
any @code{\score} block, see @ref{Multiple scores in a book}.

@lilypond[quote,ragged-right,verbatim]
\markup{ Here is some text. }
@end lilypond

@cindex font switching

The markup in the example demonstrates font switching commands.
The command @code{\bold} and @code{\italic} apply to the first
following word only; to apply a command to more than one word,
enclose the words with braces,

@example
\markup @{ \bold @{ hi there @} @}
@end example

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

@example
\markup @{ is \italic @{ anyone @} home @}
@end example

In markup mode you can compose expressions, similar to
mathematical expressions, XML documents, and music expressions.
You can stack expressions grouped vertically with the command
@code{\column}.  Similarly, @code{\center-align} aligns texts by
their center lines:

@lilypond[quote,verbatim,fragment,relative=1]
c1^\markup { \column { a bbbb \line { c d } } }
c1^\markup { \center-align { a bbbb c } }
c1^\markup { \line { a b c } }
@end lilypond

Lists with no previous command are not kept distinct.  The
expression

@example
\center-align @{ @{ a b @} @{ c d @} @}
@end example

@noindent

is equivalent to

@example
\center-align @{ a b c d @}
@end example

@noindent

To keep lists of words distinct, please use quotes @code{"} or
the @code{\line} command

@lilypond[quote,verbatim,fragment,relative=1]
\textLengthOn
c4^\markup{ \center-align { on three lines } }
c4^\markup{ \center-align { "all one line" } }
c4^\markup{ \center-align { { on three lines } } }
c4^\markup{ \center-align { \line { on one line } } }
@end lilypond

Markups can be stored in variables and these variables may be
attached to notes, like

@example
allegro = \markup @{ \bold \large @{ Allegro @} @}
 @{ a^\allegro b c d @}
@end example

Some objects have alignment procedures of their own, which cancel
out any effects of alignments applied to their markup arguments as
a whole.  For example, the @internalsref{RehearsalMark} is
horizontally centered, so using @code{\mark \markup @{ \left-align
.. @}} has no effect.

In addition, vertical placement is performed after creating the
text markup object.  If you wish to move an entire piece of
markup, you need to use the #'padding property or create an
@q{anchor} point inside the markup (generally with @code{\hspace
#0}).

@lilypond[quote,verbatim,fragment,relative=1]
\textLengthOn
c'4^\markup{ \raise #5 "not raised" }
\once \override TextScript #'padding = #3
c'4^\markup{ raised }
c'4^\markup{ \hspace #0 \raise #1.5 raised }
@end lilypond

Some situations (such as dynamic marks) have preset font-related
properties.  If you are creating text in such situations, it is
advisable to cancel those properties with @code{normal-text}.  See
@ref{Overview of text markup commands}, for more details.


@seealso

This manual: @ref{Overview of text markup commands}.

Snippets: @lsrdir{Text,Text}

Internals Reference: @internalsref{TextScript}.

Init files: @file{scm/@/new@/-markup@/.scm}.


@knownissues

Kerning or generation of ligatures is only done when the @TeX{}
backend is used.  In this case, LilyPond does not account for them
so texts will be spaced slightly too wide.

Syntax errors for markup mode are confusing.


@node Nested scores
@subsubsection Nested scores

It is possible to nest music inside markups, by adding a
@code{\score} block to a markup expression.  Such a score must
contain a @code{\layout} block.

@lilypond[quote,verbatim,ragged-right]
\relative {
  c4 d^\markup {
    \score {
      \relative { c4 d e f }
      \layout { }
    }
  }
  e f
}
@end lilypond

@seealso

Snippets: @lsrdir{Text,Text}

@node Page wrapping text
@subsubsection Page wrapping text

Whereas @code{\markup} is used to enter a non-breakable block of
text, @code{\markuplines} can be used at top-level to enter lines
of text that can spread over multiple pages:

@verbatim
\markuplines {
  \justified-lines {
    A very long text of justified lines.
    ...
  }
  \justified-lines {
    An other very long paragraph.
    ...
  }
  ...
}
@end verbatim

@code{\markuplines} accepts a list of markup, that is either the
result of a markup list command, or a list of markups or of markup
lists.  The built-in markup list commands are described in
@ref{Overview of text markup list commands}.

@seealso

This manual: @ref{Overview of text markup list commands}, @ref{New
markup list command definition}.

Snippets: @lsrdir{Text,Text}

@predefined

@funindex \markuplines
@code{\markuplines}

@node Font selection
@subsubsection Font selection

@cindex font selection
@cindex font magnification
@funindex font-interface

By setting the object properties described below, you can select a
font from the preconfigured font families.  LilyPond has default
support for the feta music fonts.  Text fonts are selected through
Pango/FontConfig.  The serif font defaults to New Century
Schoolbook, the sans and typewriter to whatever the Pango
installation defaults to.


@itemize
@item @code{font-encoding}
is a symbol that sets layout of the glyphs.  This should only be
set to select different types of non-text fonts, e.g.

@code{fetaBraces} for piano staff braces, @code{fetaMusic} the
standard music font, including ancient glyphs, @code{fetaDynamic}
for dynamic signs and @code{fetaNumber} for the number font.

@item @code{font-family}
is a symbol indicating the general class of the typeface.
Supported are @code{roman} (Computer Modern), @code{sans}, and
@code{typewriter}.

@item @code{font-shape}
is a symbol indicating the shape of the font.  There are typically
several font shapes available for each font family.  Choices are
@code{italic}, @code{caps}, and @code{upright}.

@item @code{font-series}
is a symbol indicating the series of the font.  There are
typically several font series for each font family and shape.
Choices are @code{medium} and @code{bold}.

@end itemize

Fonts selected in the way sketched above come from a predefined
style sheet.  If you want to use a font from outside the style
sheet, then set the @code{font-name} property,

@lilypond[fragment,verbatim]
{
  \override Staff.TimeSignature #'font-name = #"Charter"
  \override Staff.TimeSignature #'font-size = #2
  \time 3/4
  c'1_\markup {
    \override #'(font-name . "Vera Bold")
      { This text is in Vera Bold }
  }
}
@end lilypond

@noindent
Any font can be used, as long as it is available to
Pango/FontConfig.  To get a full list of all available fonts, run
the command

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

(the last argument of the command can be anything, but has to be
present).


The size of the font may be set with the @code{font-size}
property.  The resulting size is taken relative to the
@code{text-font-size} as defined in the @code{\paper} block.

@cindex font size
@cindex font magnification


It is also possible to change the default font family for the
entire document.  This is done by calling the
@code{make-pango-font-tree} from within the @code{\paper} block.
The function takes names for the font families to use for roman,
sans serif and monospaced text.  For example,

@cindex font families, setting
@cindex Pango


@lilypond[verbatim]
\paper  {
  myStaffSize = #20

  #(define fonts
    (make-pango-font-tree "Times New Roman"
                          "Nimbus Sans"
                          "Luxi Mono"
                           (/ myStaffSize 20)))
}

{
  c'^\markup { roman: foo \sans bla \typewriter bar }
}
@end lilypond

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



@seealso

Snippets: @lsrdir{Text,Text}


@node Special text concerns
@subsection Special text concerns

@c FIXME: this section is to be removed
@c (see comments below) -vv

@menu
* New dynamic marks::           
* Text and line spanners::      
@end menu

@node New dynamic marks
@subsubsection New dynamic marks

@c FIXME: this whole section should be removed and put in
@c "Writing text" -vv

It is possible to print new dynamic marks or text that should be
aligned with dynamics.  Use @code{make-dynamic-script} to create
these marks.  Note that the dynamic font only contains the
characters @code{f,m,p,r,s} and @code{z}.

Some situations (such as dynamic marks) have preset font-related
properties.  If you are creating text in such situations, it is
advisable to cancel those properties with @code{normal-text}.  See
@ref{Overview of text markup commands}, for more details.

@cindex make-dynamic-script

@lilypond[quote,verbatim,ragged-right]
sfzp = #(make-dynamic-script "sfzp")
\relative c' {
  c4 c c\sfzp c
}
@end lilypond

@cindex Dynamics, editorial
@cindex Dynamics, parenthesis

It is also possible to print dynamics in round parenthesis or
square brackets.  These are often used for adding editorial
dynamics.

@lilypond[quote,verbatim,ragged-right]
rndf = \markup{ \center-align {\line { \bold{\italic (}
  \dynamic f \bold{\italic )} }} }
boxf = \markup{ \bracket { \dynamic f } }
{ c'1_\rndf c'1_\boxf }
@end lilypond

@seealso

Snippets: @lsrdir{Text,Text}


@node Text and line spanners
@subsubsection Text and line spanners

@c FIXME: this whole section has to be removed.
@c glissando stuff should go into Expressive marks;
@c Text spanners should go into... Text spanners.
@c (I'm on it) --vv

Some performance indications, e.g., @i{rallentando} and
@i{accelerando} and @i{trills} are written as text and are
extended over many measures with lines, sometimes dotted or wavy.

These all use the same routines as the glissando for drawing the
texts and the lines, and tuning their behavior is therefore also
done in the same way.  It is done with a spanner, and the routine
responsible for drawing the spanners is
@code{ly:line-interface::print}.  This routine determines the
exact location of the two @i{span points} and draws a line in
between, in the style requested.

Here is an example of the different line styles available, and how
to tune them.

@lilypond[relative=2,ragged-right,verbatim,fragment]
d2 \glissando d'2
\once \override Glissando #'style = #'dashed-line
d,2 \glissando d'2
\override Glissando #'style = #'dotted-line
d,2 \glissando d'2
\override Glissando #'style = #'zigzag
d,2 \glissando d'2
\override Glissando #'style = #'trill
d,2 \glissando d'2
@end lilypond

The information that determines the end-points is computed
on-the-fly for every graphic object, but it is possible to
override these. 

@lilypond[relative=2,ragged-right,verbatim,fragment]
e2 \glissando f
\once \override Glissando #'bound-details #'right #'Y = #-2
e2 \glissando f
@end lilypond

The @code{Glissando} object, like any other using the
@code{ly:line-interface::print} routine, carries a nested
association list.  In the above statement, the value for @code{Y}
is set to @code{-2} for the association list corresponding to the
right end point.  Of course, it is also possible to adjust the
left side with @code{left} instead of @code{right}.

If @code{Y} is not set, the value is computed from the vertical
position of right attachment point of the spanner. 

In case of a line break, the values for the span-points are
extended with contents of the @code{left-broken} and
@code{right-broken} sublists, for example

@lilypond[relative=2,ragged-right,verbatim,fragment]
\override Glissando #'breakable = ##T 
\override Glissando #'bound-details #'right-broken #'Y = #-3
c1 \glissando \break
f1
@end lilypond

The following properties can be used for the

@table @code
@item Y
This sets the Y-coordinate of the end point, in staff space.  By
default, it is the center of the bound object, so for a glissando
it points to the vertical center of the note head.

For horizontal spanners, such as text spanner and trill spanners,
it is hardcoded to 0.

@item attach-dir
This determines where the line starts and ends in X-direction,
relative to the bound object.  So, a value of @code{-1} (or
@code{LEFT}) makes the line start/end at the left side of the note
head it is attached to.

@item X
This is the absolute coordinate of the end point.  It is usually
computed on the fly, and there is little use in overriding it. 

@item stencil
Line spanners may have symbols at the beginning or end, which is
contained in this sub-property.  This is for internal use, it is
recommended to use @code{text}.

@item text
This is a markup that is evaluated to yield stencil.  It is used
to put @i{cresc.} and @i{tr} on horizontal spanners.

@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
\override TextSpanner #'bound-details #'left #'text
   = \markup { \small \bold Slower }
c2\startTextSpan b c a\stopTextSpan
@end lilypond

@item stencil-align-dir-y
@item stencil-offset
Without setting this, the stencil is simply put there at the
end-point, as defined by the @code{X} and @code{Y} sub properties.
Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
will move the symbol at the edge relative to the end point of the
line

@lilypond[relative=1,fragment,verbatim]
\override TextSpanner #'bound-details
  #'left #'stencil-align-dir-y = #DOWN
\override TextSpanner #'bound-details
  #'right #'stencil-align-dir-y = #UP

\override TextSpanner #'bound-details
  #'left #'text = #"gggg"
\override TextSpanner #'bound-details
  #'right #'text = #"hhhh"
c4^\startTextSpan c c c \stopTextSpan
@end lilypond

@item arrow
Setting this sub property to @code{#t} produce an arrowhead at the
end of the line.

@item padding
This sub property controls the space between the specified
end-point of the line and the actual end.  Without padding, a
glissando would start and end in the center of each note head.

@end table

TODO: add this somewhere

@verbatim
\new Staff {
  \override TextSpanner #'bound-details #'left-broken #'text = ##f
   \override TextSpanner #'bound-details #'left #'text = \markup {
"start" }
   c'1 \startTextSpan \break
   c'1
   c'1 \stopTextSpan
}
@end verbatim


The music function \endSpanners terminates spanners and hairpins
after exactly one note.

@lilypond[verbatim,quote,ragged-right,relative=2,fragment]
\endSpanners
c2 \startTextSpan c2
c2 \< c2
@end lilypond

When using \endSpanners it is not necessary to close
\startTextSpan with \stopTextSpan, nor is it necessary to close
hairpins with \!.



@seealso

Snippets: @lsrdir{Text,Text}

Internals Reference: @internalsref{TextSpanner},
@internalsref{Glissando}, @internalsref{VoiceFollower},
@internalsref{TrillSpanner},
@internalsref{line-spanner-interface}.