@node Text
@section Text
+@lilypondfile[quote,ragged-right,line-width=16\cm,staffsize=16]
+{text-headword.ly}
+
This section explains how to include text (with various
formatting) in your scores.
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
-
@menu
* Writing text::
* Text markup::
+* Special text concerns::
@end menu
@subsection Writing text
@menu
+* Overview of text entry::
* Text scripts::
-* Text and line spanners::
* Text spanners::
* Text marks::
-* New dynamic marks::
@end menu
+@node Overview of text entry
+@unnumberedsubsubsec 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
@unnumberedsubsubsec Text scripts
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
+but by using the command @code{\textLengthOn}, the widths will be taken
into account
@lilypond[quote,fragment,ragged-right,verbatim,relative=1]
-c4^"longtext" \fatText c4_"longlongtext" c4
+c4^"longtext" \textLengthOn c4_"longlongtext" c4
@end lilypond
@noindent
-To prevent text from influencing spacing, use @code{\emptyText}.
+To prevent text from influencing spacing, use @code{\textLengthOff}.
More complex formatting may also be added to a note by using the
markup command,
@refcommands
-@funindex \fatText
-@code{\fatText},
-@funindex \emptyText
-@code{\emptyText}.
+@funindex \textLengthOn
+@code{\textLengthOn},
+@funindex \textLengthOff
+@code{\textLengthOff}.
@commonprop
@seealso
-In this manual: @ref{Text markup}.
-
-Program reference: @internalsref{TextScript}.
-
-
-@node Text and line spanners
-@unnumberedsubsubsec Text and line spanners
-
-Some performance indications, e.g., @i{rallentando} and
-@i{accelerando} and @i{trills} are written as text and are
-extended over many measures with lines, sometimes dotted or wavy.
-
-These all use the same routines as the glissando for drawing the
-texts and the lines, and tuning their behavior is therefore also
-done in the same way. It is done with a spanner, and the routine
-responsible for drawing the spanners is
-@code{ly:line-interface::print}. This routine determines the
-exact location of the two @i{span points} and draws a line in
-between, in the style requested.
-
-Here is an example of the different line styles available, and how
-to tune them.
-
-@lilypond[relative=2,ragged-right,verbatim,fragment]
-d2 \glissando d'2
-\once \override Glissando #'dash-fraction = #0.5
-d,2 \glissando d'2
-\override Glissando #'style = #'dotted-line
-d,2 \glissando d'2
-\override Glissando #'style = #'zigzag
-d,2 \glissando d'2
-\override Glissando #'style = #'trill
-d,2 \glissando d'2
-@end lilypond
+Notation Reference: @ref{Text markup}.
-The information that determines the end-points is computed
-on-the-fly for every graphic object, but it is possible to
-override these.
+Snippets: @lsrdir{Text,Text}
-@lilypond[relative=2,ragged-right,verbatim,fragment]
-e2 \glissando f
-\once \override Glissando #'bound-details #'right #'Y = #-2
-e2 \glissando f
-@end lilypond
-
-The @code{Glissando} object, like any other using the
-@code{ly:line-interface::print} routine, carries a nested
-association list. In the above statement, the value for @code{Y}
-is set to @code{-2} for the association list corresponding to the
-right end point. Of course, it is also possible to adjust the
-left side with @code{left} instead of @code{right}.
-
-If @code{Y} is not set, the value is computed from the vertical
-position of right attachment point of the spanner.
-
-In case of a line break, the values for the span-points are
-extended with contents of the @code{left-broken} and
-@code{right-broken} sublists, for example
-
-@lilypond[relative=2,ragged-right,verbatim,fragment]
-\override Glissando #'breakable = ##T
-\override Glissando #'bound-details #'right-broken #'Y = #-3
-c1 \glissando \break
-f1
-@end lilypond
-
-The following properties can be used for the
-
-@table @code
-@item Y
-This sets the Y-coordinate of the end point, in staff space. By
-default, it is the center of the bound object, so for a glissando
-it points to the vertical center of the note head.
-
-For horizontal spanners, such as text spanner and trill spanners,
-it is hardcoded to 0.
-
-@item attach-dir
-This determines where the line starts and ends in X-direction,
-relative to the bound object. So, a value of @code{-1} (or
-@code{LEFT}) makes the line start/end at the left side of the note
-head it is attached to.
-
-@item X
-This is the absolute coordinate of the end point. It is usually
-computed on the fly, and there is little use in overriding it.
-
-@item stencil
-Line spanners may have symbols at the beginning or end, which is
-contained in this sub-property. This is for internal use, it is
-recommended to use @code{text}.
-
-@item text
-This is a markup that is evaluated to yield stencil. It is used
-to put @i{cresc.} and @i{tr} on horizontal spanners.
-
-@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
-\override TextSpanner #'bound-details #'left #'text
- = \markup { \small \bold Slower }
-c2\startTextSpan b c a\stopTextSpan
-@end lilypond
-
-@item stencil-align-dir-y
-@item stencil-offset
-Without setting this, the stencil is simply put there at the
-end-point, as defined by the @code{X} and @code{Y} sub properties.
-Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
-will move the symbol at the edge relative to the end point of the
-line
-
-@lilypond[relative=1,fragment,verbatim]
-\override TextSpanner #'bound-details
- #'left #'stencil-align-dir-y = #DOWN
-\override TextSpanner #'bound-details
- #'right #'stencil-align-dir-y = #UP
-
-\override TextSpanner #'bound-details
- #'left #'text = #"gggg"
-\override TextSpanner #'bound-details
- #'right #'text = #"hhhh"
-c4^\startTextSpan c c c \stopTextSpan
-@end lilypond
-
-@item arrow
-Setting this sub property to @code{#t} produce an arrowhead at the
-end of the line.
-
-@item padding
-This sub property controls the space between the specified
-end-point of the line and the actual end. Without padding, a
-glissando would start and end in the center of each note head.
-
-@end table
-
-TODO: add this somewhere
-
-@verbatim
-\new Staff {
- \override TextSpanner #'bound-details #'left-broken #'text = ##f
- \override TextSpanner #'bound-details #'left #'text = \markup {
-"start" }
- c'1 \startTextSpan \break
- c'1
- c'1 \stopTextSpan
-}
-@end verbatim
-
-
-@seealso
-
-Program reference: @internalsref{TextSpanner},
-@internalsref{Glissando}, @internalsref{VoiceFollower},
-@internalsref{TrillSpanner},
-@internalsref{line-spanner-interface}.
-
-Examples: @lsr{expressive,line-styles.ly},
-@lsr{expressive,line-arrows.ly}
+Internals Reference: @internalsref{TextScript}.
@node Text spanners
To print a solid line, use
@example
-\override TextSpanner #'dash-fraction = #'()
+\override TextSpanner #'style = #'line
@end example
@seealso
-Program reference: @internalsref{TextSpanner}.
+Snippets: @lsrdir{Text,Text}
+
+Internals Reference: @internalsref{TextSpanner}.
@node Text marks
@seealso
-Program reference: @internalsref{RehearsalMark}.
-
-
+Snippets: @lsrdir{Text,Text}
-@node New dynamic marks
-@unnumberedsubsubsec New dynamic marks
-
-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
+Internals Reference: @internalsref{RehearsalMark}.
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}.
-Program reference: @internalsref{TextScript}.
+Snippets: @lsrdir{Text,Text}
+
+Internals Reference: @internalsref{TextScript}.
Init files: @file{scm/@/new@/-markup@/.scm}.
}
@end lilypond
+@seealso
+
+Snippets: @lsrdir{Text,Text}
+
@node Page wrapping text
@unnumberedsubsubsec Page wrapping text
This manual: @ref{Overview of text markup list commands}, @ref{New
markup list command definition}.
+Snippets: @lsrdir{Text,Text}
+
@refcommands
@funindex \markuplines
installation defaults to.
-@itemize @bullet
+@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.
@seealso
-Examples: @lsr{text,font@/-family@/-override.ly}.
+Snippets: @lsrdir{Text,Text}
+
+
+@node Special text concerns
+@subsection Special text concerns
+
+
+
+@menu
+* New dynamic marks::
+* Text and line spanners::
+@end menu
+
+@node New dynamic marks
+@unnumberedsubsubsec New dynamic marks
+
+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}
+
+
+@node Text and line spanners
+@unnumberedsubsubsec Text and line spanners
+
+Some performance indications, e.g., @i{rallentando} and
+@i{accelerando} and @i{trills} are written as text and are
+extended over many measures with lines, sometimes dotted or wavy.
+
+These all use the same routines as the glissando for drawing the
+texts and the lines, and tuning their behavior is therefore also
+done in the same way. It is done with a spanner, and the routine
+responsible for drawing the spanners is
+@code{ly:line-interface::print}. This routine determines the
+exact location of the two @i{span points} and draws a line in
+between, in the style requested.
+
+Here is an example of the different line styles available, and how
+to tune them.
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+d2 \glissando d'2
+\once \override Glissando #'style = #'dashed-line
+d,2 \glissando d'2
+\override Glissando #'style = #'dotted-line
+d,2 \glissando d'2
+\override Glissando #'style = #'zigzag
+d,2 \glissando d'2
+\override Glissando #'style = #'trill
+d,2 \glissando d'2
+@end lilypond
+
+The information that determines the end-points is computed
+on-the-fly for every graphic object, but it is possible to
+override these.
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+e2 \glissando f
+\once \override Glissando #'bound-details #'right #'Y = #-2
+e2 \glissando f
+@end lilypond
+
+The @code{Glissando} object, like any other using the
+@code{ly:line-interface::print} routine, carries a nested
+association list. In the above statement, the value for @code{Y}
+is set to @code{-2} for the association list corresponding to the
+right end point. Of course, it is also possible to adjust the
+left side with @code{left} instead of @code{right}.
+
+If @code{Y} is not set, the value is computed from the vertical
+position of right attachment point of the spanner.
+
+In case of a line break, the values for the span-points are
+extended with contents of the @code{left-broken} and
+@code{right-broken} sublists, for example
+
+@lilypond[relative=2,ragged-right,verbatim,fragment]
+\override Glissando #'breakable = ##T
+\override Glissando #'bound-details #'right-broken #'Y = #-3
+c1 \glissando \break
+f1
+@end lilypond
+
+The following properties can be used for the
+
+@table @code
+@item Y
+This sets the Y-coordinate of the end point, in staff space. By
+default, it is the center of the bound object, so for a glissando
+it points to the vertical center of the note head.
+
+For horizontal spanners, such as text spanner and trill spanners,
+it is hardcoded to 0.
+
+@item attach-dir
+This determines where the line starts and ends in X-direction,
+relative to the bound object. So, a value of @code{-1} (or
+@code{LEFT}) makes the line start/end at the left side of the note
+head it is attached to.
+
+@item X
+This is the absolute coordinate of the end point. It is usually
+computed on the fly, and there is little use in overriding it.
+
+@item stencil
+Line spanners may have symbols at the beginning or end, which is
+contained in this sub-property. This is for internal use, it is
+recommended to use @code{text}.
+
+@item text
+This is a markup that is evaluated to yield stencil. It is used
+to put @i{cresc.} and @i{tr} on horizontal spanners.
+
+@lilypond[quote,ragged-right,fragment,relative=2,verbatim]
+\override TextSpanner #'bound-details #'left #'text
+ = \markup { \small \bold Slower }
+c2\startTextSpan b c a\stopTextSpan
+@end lilypond
+
+@item stencil-align-dir-y
+@item stencil-offset
+Without setting this, the stencil is simply put there at the
+end-point, as defined by the @code{X} and @code{Y} sub properties.
+Setting either @code{stencil-align-dir-y} or @code{stencil-offset}
+will move the symbol at the edge relative to the end point of the
+line
+
+@lilypond[relative=1,fragment,verbatim]
+\override TextSpanner #'bound-details
+ #'left #'stencil-align-dir-y = #DOWN
+\override TextSpanner #'bound-details
+ #'right #'stencil-align-dir-y = #UP
+
+\override TextSpanner #'bound-details
+ #'left #'text = #"gggg"
+\override TextSpanner #'bound-details
+ #'right #'text = #"hhhh"
+c4^\startTextSpan c c c \stopTextSpan
+@end lilypond
+
+@item arrow
+Setting this sub property to @code{#t} produce an arrowhead at the
+end of the line.
+
+@item padding
+This sub property controls the space between the specified
+end-point of the line and the actual end. Without padding, a
+glissando would start and end in the center of each note head.
+
+@end table
+
+TODO: add this somewhere
+
+@verbatim
+\new Staff {
+ \override TextSpanner #'bound-details #'left-broken #'text = ##f
+ \override TextSpanner #'bound-details #'left #'text = \markup {
+"start" }
+ c'1 \startTextSpan \break
+ c'1
+ c'1 \stopTextSpan
+}
+@end verbatim
+
+
+The music function \endSpanners terminates spanners and hairpins
+after exactly one note.
+
+@lilypond[verbatim,quote,ragged-right,relative=2,fragment]
+\endSpanners
+c2 \startTextSpan c2
+c2 \< c2
+@end lilypond
+
+When using \endSpanners it is not necessary to close
+\startTextSpan with \stopTextSpan, nor is it necessary to close
+hairpins with \!.
+
+
+
+@seealso
+
+Snippets: @lsrdir{Text,Text}
+
+Internals Reference: @internalsref{TextSpanner},
+@internalsref{Glissando}, @internalsref{VoiceFollower},
+@internalsref{TrillSpanner},
+@internalsref{line-spanner-interface}.
+
projects / lilypond.git / blobdiff