Standardize introduciton of snippets.

[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.38"

@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

It is possible to add arbitrary text indications
to a score, as demonstrated in the following example.
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 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{Controlling direction and placement}.

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

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

Such objects, called @q{spanners}, may be created
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

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:
@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;
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; 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

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

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

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

@seealso

Notation Reference: @ref{Rehearsal marks},
@ref{Formatting text}, @ref{The Feta font}.

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
@c  A workaround is suggested in the first @snippets item -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[quote,ragged-right,verbatim]
\markup {
  Tomorrow, and tomorrow, and tomorrow...
}
@end lilypond

@noindent
This allows to print 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}.

@ignore
@snippets

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

@seealso

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

Snippets:
@lsrdir{Text,Text}

Internals Reference: @internalsref{TextScript}.

@predefined

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


@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

A @code{\markup} block is used to typeset text with an extensible syntax,
called @q{markup mode}.
Specific commands can be entered in this mode, using the
backslash @code{\} character.
@c TODO: move the following sentence (and add an example?) -vv
To @emph{print} such characters as
@code{\} and @code{#} in the output, 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
An exhaustive list of @code{\markup}-specific commands can be found in
@ref{Text markup commands}.


@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



@cindex font switching

Some font switching commands are demonstrated here. Such commands
apply only to the first following word; several words may be affected
by enclosing them in braces.

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

@c TODO: remove the following line and example? -vv
@noindent
For clarity, you can also do this for single arguments, e.g.,

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

The markup mode can be used to compose expressions, similar to
mathematical expressions, XML documents, and music expressions.
Such expressions can be vertically stacked, horizontally centered, 
or aligned in different ways:

@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.  In
the following example, the two @code{\markup} expressions
are equivalent:

@c TODO: merge these two examples in a @lilypond example -vv

@example
\center-align @{ @{ a b @} @{ c d @} @}
\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{Text markup commands}, for more details.

@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


\null
\hspace

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

@end ignore

@seealso

This manual: @ref{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 Common markup commands
@subsubsection Common markup commands

Some basic formatting can be used blah blah

\italic 
\upright
\bold 
\medium 
\underline
        

@c TODO: what's the difference between the following commands? -vv
\smallCaps      
\caps 
\fontCaps


Some alternate font families can easily be selected:

\sans
\typewriter
\roman
\number (only for numbers, such as fingerings and time signatures)
@c TODO: add \slashed-digit here? -vv

The size can be blah blah blah

\fontsize

Some predefined font sizes can be used blah blah

\teeny
\tiny
\small  
\normalsize
\large
\huge

Some shorcuts allow to change the font size relatively to its previous value 

\smaller
\bigger
\larger

\magnify

Text may be printed as subscript or superscript:

\sub 
\super

To obtain subscripts or superscripts in a normal text size, use
\normal-size-sub
\normal-size-super

All these settings (except the size) can be reverted to the default font:

\normal-text 


@node Text alignment
@subsubsection Text alignment

Alignment basics:
\left-align
\center-align
\right-align

Horizontal alignment:
\hcenter
\general-align
\halign 


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

@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:
@lsrdir{Text,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:
@lsrdir{Text,Text}

@predefined

@funindex \markuplines
@code{\markuplines}



@c TODO: move the following subsubsec into NR3 -vv
@c maybe.  -gp
@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:
@lsrdir{Text,Text}