Merge branch 'master' of ssh+git://hanwen@git.sv.gnu.org/srv/git/lilypond

[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

If specified, text marks may be aligned with notation objects
other than bar lines.  These objects include @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}.


In such cases, text marks will be, by default, horizontally centered
above the object. However, this can be changed, as demonstrated
on the second line of this example (in a score with multiple staves,
this setting should be done for all the staves).


@lilypond[fragment,quote,ragged-right,verbatim,relative=1]
  e1
  
  % the RehearsalMark will be centered above the Clef
  \override Score.RehearsalMark #'break-align-symbols = #'(clef)
  \key a \major
  \clef treble
  \mark "↓"
  e
  
  % the RehearsalMark will be centered above the TimeSignature
  \override Score.RehearsalMark #'break-align-symbols = #'(time-signature)
  \key a \major
  \clef treble
  \time 3/4
  \mark "↓"
  e2.
  
  % the RehearsalMark will be centered above the KeySignature
  \override Score.RehearsalMark #'break-align-symbols = #'(key-signature)
  \key a \major
  \clef treble
  \time 4/4
  \mark "↓"
  e1

  \break
  e
  
  % the RehearsalMark will be aligned with the left edge of the KeySignature
  \once \override Score.KeySignature #'break-align-anchor-alignment = #LEFT
  \mark "↓"
  \key a \major
  e
  
  % the RehearsalMark will be aligned with the right edge of the KeySignature
  \once \override Score.KeySignature #'break-align-anchor-alignment = #RIGHT
  \key a \major
  \mark "↓"
  e
  
  % the RehearsalMark will be aligned with the left edge of the KeySignature
  % and then shifted right by 1 unit.
  \once \override Score.KeySignature #'break-align-anchor = #1
  \key a \major
  \mark "↓"
  e1
@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::           
@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}