@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
-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}.
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
-
-@lilypond[fragment,ragged-right,staffsize=16,quote]
-c'4^\markup { bla \bold bla }
-@end lilypond
+@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::
@end menu
@node Overview of text entry
-@unnumberedsubsubsec Overview of text entry
+@subsubsection Overview of text entry
There are four ways to add text to scores:
@end itemize
+@seealso
+
+Snippets: @lsrdir{Text,Text}
+
@node Text scripts
-@unnumberedsubsubsec Text scripts
+@subsubsection Text scripts
@cindex Text scripts
@cindex text items, non-empty
@cindex non-empty texts
It is possible to place arbitrary strings of text or @ref{Text
-markup}, above or below notes by using a string @code{c^"text"}.
-By default, these indications do not influence the note spacing,
-but by using the command @code{\fatText}, the widths will be taken
-into account
+markup} with @var{note}@code{-"}@var{text}@code{"}.
-@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-c4^"longtext" \fatText c4_"longlongtext" c4
-@end lilypond
-
-@noindent
-To prevent text from influencing spacing, use @code{\emptyText}.
+INSERT EXAMPLE
More complex formatting may also be added to a note by using the
-markup command,
+@code{\markup} command, as described in @ref{Text markup}.
@lilypond[fragment,ragged-right,verbatim,quote]
c'4^\markup { bla \bold bla }
@end lilypond
-The @code{\markup} is described in more detail in @ref{Text
-markup}.
+@predefined
+@funindex \textLengthOn
+@code{\textLengthOn},
+@funindex \textLengthOff
+@code{\textLengthOff}.
-@refcommands
-@funindex \fatText
-@code{\fatText},
-@funindex \emptyText
-@code{\emptyText}.
+@snippets
+@c TODO: put this in the LSR. -vv
+By default, these indications do not influence the note spacing.
+However, by using the command @code{\textLengthOn}, the widths
+will be taken into account:
+@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
+c4^"this does not affect spacing" \textLengthOn c4_"whereas this does" c4
+@end lilypond
+
+@noindent
+After having used such a command, to go back to the default behavior
+and prevent text from influencing spacing, use @code{\textLengthOff}.
-@commonprop
+@c TODO: LSR-ize this as well -vv
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
Notation Reference: @ref{Text markup}.
+Snippets: @lsrdir{Text,Text}
+
Internals Reference: @internalsref{TextScript}.
@node Text spanners
-@unnumberedsubsubsec 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. Such texts are created using text
spanners; attach @code{\startTextSpan} and @code{\stopTextSpan} to
the first and last notes of the spanner.
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c1
+\override TextSpanner #'bound-details #'left #'text = "faster"
+c2\startTextSpan b c\stopTextSpan a
+@end lilypond
+
+@noindent
The string to be printed, as well as the style, is set through
-object properties
+object properties. It can accept @code{\markup} blocks as well:
@lilypond[quote,ragged-right,fragment,relative=1,verbatim]
c1
c2\startTextSpan b c\stopTextSpan a
@end lilypond
-@refcommands
+@predefined
@funindex textSpannerUp
@code{\textSpannerUp},
@code{\textSpannerNeutral}.
-@commonprop
+@snippets
To print a solid line, use
@seealso
+Snippets: @lsrdir{Text,Text}
+
Internals Reference: @internalsref{TextSpanner}.
@node Text marks
-@unnumberedsubsubsec Text marks
+@subsubsection Text marks
@cindex coda on bar line
@cindex segno on bar line
@funindex \mark
The @code{\mark} command is primarily used for @ref{Rehearsal
-marks}, but it can also be used to put signs like coda, segno, and
-fermata on a bar line. Use @code{\markup} to access the
-appropriate symbol (symbols are listed in @ref{The Feta font}).
+marks}, but it can also be used to add text elements in a score:
+
+@lilypond[verbatim,quote,ragged-right,fragment,relative=2]
+c4\mark "text" c c c
+@end lilypond
+
+As it can contain a @code{\markup} object, the @code{\mark} command
+makes possible to put any text, but also signs like coda, segno, or
+fermata on a bar line. The appropriate symbol has to be specified in
+the @code{\markup} block; these symbols are listed in @ref{The Feta font}.
@lilypond[fragment,quote,ragged-right,verbatim,relative=2]
c1 \mark \markup { \musicglyph #"scripts.ufermata" }
@end lilypond
@noindent
-@code{\mark} is only typeset above the top stave of the score. If
+@code{\mark} is only typeset above the top staff of the score. If
you specify the @code{\mark} command at a bar line, the resulting
mark is placed above the bar line. If you specify it in the
middle of a bar, the resulting mark is positioned between notes.
@c IMO this is a bug; hopefully it'll be fixed soon, so I can
@c delete this sentence. -gp
+@noindent
If there is no next line, then the mark will not be printed at
all.
-@commonprop
+@snippets
+
+@c TODO: to be LSR-ized stuff -vv
To print the mark at the end of the current line, use
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.
+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]
{
\key cis \major
% the RehearsalMark will be aligned with the left edge of the KeySignature
- \once \override Staff.KeySignature #'break-align-anchor-alignment = #LEFT
+ \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 Staff.KeySignature #'break-align-anchor-alignment = #RIGHT
+ \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 Staff.KeySignature #'break-align-anchor = #2
+ \once \override Score.KeySignature #'break-align-anchor = #2
\mark \default
ces1
}
@seealso
-Internals Reference: @internalsref{RehearsalMark}.
+Snippets: @lsrdir{Text,Text}
+Internals Reference: @internalsref{RehearsalMark}.
+@c TODO: add this here? -vv
+@c @node Text marks
+@c @subsubsection Text marks
@node Text markup
@subsection Text markup
@end menu
@node Text markup introduction
-@unnumberedsubsubsec Text markup introduction
+@subsubsection Text markup introduction
@cindex markup
@cindex text markup
the @code{\line} command
@lilypond[quote,verbatim,fragment,relative=1]
-\fatText
+\textLengthOn
c4^\markup{ \center-align { on three lines } }
c4^\markup{ \center-align { "all one line" } }
c4^\markup{ \center-align { { on three lines } } }
#0}).
@lilypond[quote,verbatim,fragment,relative=1]
-\fatText
+\textLengthOn
c'4^\markup{ \raise #5 "not raised" }
\once \override TextScript #'padding = #3
c'4^\markup{ raised }
This manual: @ref{Overview of text markup commands}.
+Snippets: @lsrdir{Text,Text}
+
Internals Reference: @internalsref{TextScript}.
Init files: @file{scm/@/new@/-markup@/.scm}.
-@refbugs
+@knownissues
Kerning or generation of ligatures is only done when the @TeX{}
backend is used. In this case, LilyPond does not account for them
@node Nested scores
-@unnumberedsubsubsec 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
}
@end lilypond
+@seealso
+
+Snippets: @lsrdir{Text,Text}
+
@node Page wrapping text
-@unnumberedsubsubsec 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
This manual: @ref{Overview of text markup list commands}, @ref{New
markup list command definition}.
-@refcommands
+Snippets: @lsrdir{Text,Text}
+
+@predefined
@funindex \markuplines
@code{\markuplines}
@node Font selection
-@unnumberedsubsubsec Font selection
+@subsubsection Font selection
@cindex font selection
@cindex font magnification
@seealso
-Examples: @lsr{text,font@/-family@/-override.ly}.
+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
-@unnumberedsubsubsec 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
{ c'1_\rndf c'1_\boxf }
@end lilypond
+@seealso
+
+Snippets: @lsrdir{Text,Text}
+
@node Text and line spanners
-@unnumberedsubsubsec 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
@lilypond[relative=2,ragged-right,verbatim,fragment]
d2 \glissando d'2
-\once \override Glissando #'dash-fraction = #0.5
+\once \override Glissando #'style = #'dashed-line
d,2 \glissando d'2
\override Glissando #'style = #'dotted-line
d,2 \glissando d'2
The music function \endSpanners terminates spanners and hairpins
after exactly one note.
-@lilypond[verbatim,quote,raged-right,relative=2,fragment]
+@lilypond[verbatim,quote,ragged-right,relative=2,fragment]
\endSpanners
c2 \startTextSpan c2
c2 \< c2
@seealso
+Snippets: @lsrdir{Text,Text}
+
Internals Reference: @internalsref{TextSpanner},
@internalsref{Glissando}, @internalsref{VoiceFollower},
@internalsref{TrillSpanner},
@internalsref{line-spanner-interface}.
-Examples: @lsr{expressive,line-styles.ly},
-@lsr{expressive,line-arrows.ly}
+
projects / lilypond.git / blobdiff