From: Graham Percival <graham@percival-music.ca>
Date: Sat, 6 Oct 2007 05:07:15 +0000 (-0700)
Subject: First draft of Text.
X-Git-Tag: release/2.11.35-1~46^2~74
X-Git-Url: https://git.donarmstrong.com/?a=commitdiff_plain;h=e82de7427ef56df5e7d49694999dfa671582dbb8;p=lilypond.git

First draft of Text.
---

diff --git a/Documentation/user/text.itely b/Documentation/user/text.itely
index a5899b535b..148a4f9697 100644
--- a/Documentation/user/text.itely
+++ b/Documentation/user/text.itely
@@ -37,6 +37,7 @@ c'4^\markup { bla \bold bla }
 @menu
 * Writing text::                
 * Text markup::                 
+* Special text concerns::       
 @end menu
 
 
@@ -44,13 +45,56 @@ c'4^\markup { bla \bold bla }
 @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
+
+
+
 @node Text scripts
 @unnumberedsubsubsec Text scripts
 
@@ -109,160 +153,6 @@ 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
-
-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
-
-
-@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}
-
-
 @node Text spanners
 @unnumberedsubsubsec Text spanners
 
@@ -458,44 +348,6 @@ Program reference: @internalsref{RehearsalMark}.
 
 
 
-@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
-
-
-
 @node Text markup
 @subsection Text markup
 
@@ -838,5 +690,205 @@ sans serif and monospaced text.  For example,
 Examples: @lsr{text,font@/-family@/-override.ly}.
 
 
+@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
+
+
+@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
+
+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
+
+
+@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}
+