Merge branch 'master' into dev/texi2html

[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}:

@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::    
* Common markup commands::      
* 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{#}).
Quoted text even allows to print double quotation marks, by preceding
them 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 kept distinct.  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 are confusing.


@node Common markup commands
@subsubsection Common markup commands

Markup text may be formatted in different ways.

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

Basic font switching is supported:

@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
other commands allow to change the size 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

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 word and the following words.

@lilypond[quote,verbatim]
\markup {
  \column {
    \line { Act \number 1 }
    \line { \sans { Scene I. } }
    \line { \typewriter { Verona. An open place. } }
    \line { \roman Enter 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}.


Defining custom font sets is also possible, as explained in
@ref{Fonts}.  An exhaustive list of font-switching, font-size
and font-families related commands can be found in @ref{Font}.

@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

@knownissues
When used inside a word, some of these commands may produce an unwanted
blank space.  This can easily be solved by concatenating the text
elements together, using a specific command
described in @ref{Text alignment}.



@node Text alignment
@subsubsection Text alignment

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

Markup objects can 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 { \center-align { poco } }
e'
a,-\markup { \right-align poco }
@end lilypond

@c FIXME: \center-align actually doesn't belong here
@c \center-align vs \column
@c \center-align vs \hcenter

Horizontal alignment:
\hcenter
\general-align
\halign 


\null
\hspace

\lower
\raise 
\translate 
\translate-scaled
\rotate
\transparent
\whiteout

Vertical alignment: 
\vcenter
\column 
\dir-column 

Building a "large" markup:

\line

\fill-line

\hcenter-in
        
\pad-around
\pad-markup
\pad-to-box
\pad-x
        
Alignment inside a "large" markup:

\justify-field 
\justify
\justify-string

\wordwrap-field
\wordwrap
\wordwrap-string


@ignore
TODO: here are some commands that could be described here.
I'm putting them in bulk, prior to working on this section. -vv

\simple

\char
\fraction

\combine
\concat
\put-adjacent


\page-ref (see also "Table of contents")
\fromproperty
\verbatim-file
\with-url

\on-the-fly 
\override



@end ignore


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 @rinternals{RehearsalMark} is
horizontally centered, so using @code{\mark \markup @{ \left-align
.. @}} has no effect.



@node Graphic notation inside markup
@subsubsection Graphic notation inside markup
Graphics around text:
\box
\circle

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