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

@c \version "2.11.51"

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


@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::                
* Formatting text::             
* Fonts::                       
@end menu


@node Writing text
@subsection Writing text

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

@menu
* Text scripts::                
* Text spanners::               
* Text marks::                  
* Separate text::               
@end menu


@node Text scripts
@subsubsection Text scripts

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

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

@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
d8^"pizz." e f g 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,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{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
@subsubsection 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 @q{spanners}, may be created
from one note to another 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, as described in @ref{Formatting text}.

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

@predefined

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

@seealso

Notation Reference: @ref{Line styles}.

Snippets:
@rlsr{Text}.

Internals Reference: @rinternals{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}:

@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,ragged-right,fragment,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}.  This can be used to print
signs like coda, segno or fermata, by specifying the appropriate
symbol name:

@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; 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 the
beginning of a score or at a line break, marks 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 "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{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
@subsubsection 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,ragged-right,verbatim]
\score {
  c'1
}
\markup {
  Tomorrow, and tomorrow, and tomorrow...
}
\score {
  c'1
}
@end lilypond

Using a specific syntax, text blocks can be spread
over multiple pages, making possible to print
text documents or books -- and therefore to
use LilyPond as a word processor.  This syntax is described in
@ref{Multi-page markup}.

@predefined

@code{\markup},
@funindex \markuplines
@code{\markuplines}

@ignore
@snippets

TODO: add convenient snippets in input/new -vv
@end ignore

@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
@subsubsection 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
specific 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{} @}}.

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

@lilypond[quote,verbatim,fragment,relative=1]
e1-\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, which
can be useful to print special characters such as @code{\} and @code{#},
or even double quotation marks -- these have to be preceded
with backslashes:

@lilypond[quote,verbatim,fragment,relative=1]
\clef bass
a^\markup "##\ LEPORELLO \##"
a_\markup "Bravi! \"Cosa rara\"!"
r a8 d
cis a r4 r2
@end lilypond

The way markup expressions are defined affects 
how these expressions will stacked, centered and aligned
when using the commands explained in @ref{Text alignment}.

@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 of words that are not enclosed with double quotes
or preceded by a command are not treated as a distinct
expression.  In the following example, the first two
@code{\markup} expressions are equivalent:

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


Markups can be stored in variables.  These 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

This manual: @ref{Text markup commands}.

Snippets:
@rlsr{Text}.

Internals Reference: @rinternals{TextScript}.

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


@knownissues

Syntax errors for markup mode can be confusing.


@node Selecting font and font size
@subsubsection 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 \bigger
@funindex \magnify

The size of the characters can also be altered in different ways:
@itemize
@item
the font size can be defined to an absolute value,

@item
predefined commands allow to easily select standard sizes,

@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=2]
{
  f1^\markup { \fontsize #5 Sinfonia } 
  a,_\markup { 
    \tiny espressivo
    \large e
    \normalsize intenso 
  }
  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, font-size
and font-families related commands can be found in @ref{Font}.

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

@predefined

@funindex \teeny
@funindex \tiny
@funindex \small
@funindex \normalsize
@funindex \large
@funindex \huge
@code{\teeny},
@code{\tiny},
@code{\small},
@code{\normalsize},
@code{\large},
@code{\huge}.

@c TODO: add @seealso


@node Text alignment
@subsubsection Text alignment

@cindex text, aligning
@cindex aligning text

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

@c The 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 \hcenter
@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's no difference
between the first and the second markup.

@lilypond[quote,verbatim,fragment,relative=1]
a1-\markup { poco }
e'
a,-\markup { \left-align poco }
e'
a,-\markup { \hcenter { poco } }
e'
a,-\markup { \right-align poco }
@end lilypond

@funindex \halign

The horizontal alignment may be fine-tuned
using a numeric value:

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

@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-align {
    a
    "b c"
    \line { d e f }
  }
}
@end lilypond

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-align {
      \huge \smallCaps "The Mikado"
      or
      \smallCaps "The Town of Titipu"
    }
    \line { Sir Arthur Sullivan }
  }
}
\markup {
  \fill-line { 1885 } 
}
@end lilypond

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

@c TODO: add @seealso

@node Graphic notation inside markup
@subsubsection Graphic notation inside markup

Graphics around text:
\box
\circle

(TODO: document padding commands here)

\bracket
\hbracket

"Standalone" graphics:

\arrow-head
\draw-line
\draw-circle
\filled-box
\triangle
\strut

\with-color


Advanced graphics:
\stencil

\postscript
\epsfile

\with-dimensions

@node Music notation inside markup
@subsubsection Music notation inside markup

Notes can be printed in markup mode blah blah:

\note   
\note-by-number

Accidental symbols can be obtained easily:

\doubleflat
\sesquiflat
\flat
\semiflat
\natural
\semisharp
\sharp
\sesquisharp
\doublesharp

Some other notation objects blah blah

\beam
\finger
\dynamic
\tied-lyric
\markalphabet
\markletter
@c TODO: add \text here? -vv

Any musical symbol can be printed

\musicglyph
@c TODO: add \lookup here? -vv


The markup mode has support for fret diagrams:

\fret-diagram 
\fret-diagram-terse
\fret-diagram-verbose

An entire @code{\score} block can even be nested in a @code{\markup}
block.  In such a case, the @code{\score} must contain a @code{\layout} block.


\score


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

@seealso

Snippets:
@rlsr{Text}.

@node Multi-page markup
@subsubsection Multi-page markup

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

@seealso

This manual: @ref{Text markup list commands}, @ref{New
markup list command definition}.

Snippets:
@rlsr{Text}.

@predefined

@funindex \markuplines
@code{\markuplines}


@node Fonts
@subsection Fonts

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

@node Entire document fonts
@subsubsection Entire document fonts

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


@node Single entry fonts
@subsubsection Single entry fonts

@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




@seealso

Snippets:
@rlsr{Text}.