13 Text

13.1 Introduction

SVG allows text to be inserted into the drawing. All of the
same styling attributes available for paths and vector
graphic shapes are also available for text.
(See Filling, Stroking and Paint Servers.)

13.2 The <text> element

The <text> element adds text to a drawing.

SVG requires that all SVG text data be specified within a
<text> element.
This allows the SVG user agent to know unambiguously how to
render the text. Furthermore, it provides enough information
to the SVG user agent to allow it to stitch together separately
drawn strings of text into textflows.
(See Defining Text Flows: the <textflow> element.)

You have two choices for how to specify the text strings to be drawn:

As standard XML character data between <text> and </text>

By providing a <textsrc href="..." /> subelement to a
<text> element. (The <textsrc> element
is defined as an XLink.
Note that the XLink specification is currently under development
and is subject to change. The SVG working group will track and rationalize with XLink
as it evolves.)
The text string to be used is the character data within the element(s)
referenced by the <uri> value given as the value of href.

In the example below, the first <text> element (with id="TextToUse")
will not draw because
it is part of a <defs> element. The second <text> element draws the
string "ABC".
The third text element draws the string "XYZ" because it includes
a <textsrc> element which is a reference to element "TextToUse", and that
element's character data is "XYZ":

<text> elements which are not positioned along a path
(see Text On A Path below)
can supply optional attributes
x= and y=
which represents the location in
user coordinates (or Transformed CSS units or a percentage of
the current viewport) for the initial current text position.
(Default values for x= and y= are the previous
current text position from the end of the previous <text>
element within the same <textflow> or,
if there is no such
previous <text> element, zero in the user coordinate system .)
For left-aligned character strings, the placement point of the first glyph
will be positioned exactly at the current text position
and the glyph will be rendered based on the current set of text and
font properties. After the glyph is rendered, the current text position
is advanced based on the metrics of the glyph that were used along with the current
set of text and font properties. For Roman text,
the current text position is advanced along the x-axis by
the width of that glyph. The cycle repeats until all characters in
the <text> element have been rendered.

(Internationalization issues need to be addressed.)

13.3 Defining Text Flows

SVG provides <textblock> and <textflow> elements
to allow generators of SVG to specify text selection order,
even when the contents of a text flow are distributed throughout
the canvas.
When feasible, generators of SVG should attempt to use this facility
to order their text strings
to facilitate properly ordered text selection within SVG viewing applications such as Web
browsers.

13.3.1 The <textblock> element

The <textblock> element identifies a simple text flow
consisting of a sequence of consecutive <text> elements.
For the first <text> element, the starting position
is (0,0) in the current user coordinate system. (Any transform
or x or y attributes serve to alter the
current user coordinate system and thus define a new origin.)
For subsequent <text> elements,
the initial current coordinate system represents the current coordinate system
of the previous <text> element, plus a translation
to take into account the text advances that occurred as the characters
in the previous <text> element were drawn. (Note that these changes
in the user coordinate system only have effect within the scope of the
<textblock> element.)

A <textblock> element
can only contain <text> elements as its children.

13.3.2 The <textflow> element

The <textflow> element defines the selection
order for multiple <textblock> elements within a given SVG document.
Its main usage is when the desired text selection order of a document is
more complex than what can be described using the <textblock> element.

A <textflow> element can contain any combination of
<tref> child elements
which are references to <textblock> elements defined elsewhere.

Within an SVG viewing application which supports text selection,
the following behavior should exist.
When the mouse is clicked over an SVG character and then the
mouse is dragged, whenever the mouse goes over another character within the
same <textflow>, all characters whose selection order is between
the initial character and the current character should be highlighted,
no matter where they might be located on the canvas.

(??? Insert drawing here)

13.4 Text and Font Properties

(Descriptions (or references to the CSS2 spec)
for all of the text and font properties from CSS2 go here.
The following are SVG-specific text properties which go beyond
the text and font properties already defined in CSS2:)

'text-antialiasing' indicates whether text strings should
be drawn with antialiased rendering. This property is a hint to the user agent
which is expected to be honored in commercial SVG user agents.

true

Text strings should be drawn with antialiased rendering.

false

Text strings should be drawn without antialiasing.

13.5 Ligatures and Alternate Glyphs

There are situations such as ligatures, special-purpose fonts (e.g.,
a font for music symbols) or alternate glyphs for Asian text strings where
a different glyph should be used to render some text than the glyph
which normally corresponds to the given character data. Also,
the W3C Character Model (??? add link) requires early normalization
of character data to facilitate meaningful and unambiguous exchange of character
data and correct comparisons between character strings. The W3C Character
Model will bring about many common situations where the normalized character data
will be different than the glyphs which the user want to use to render that character data.

To allow for control over the glyphs used to render particular character data,
the 'altglyph' property is available.

where <value> indicates a string of Unicode characters that should replace
the text within the <text> element

glyphname(<string>))

where <string> provides a string of which is the name of the glyph that should
be used to replace the text within the <text> element

glyphid(<value>))

where <value> a string of which is numeric ID/index of the glyph
that should be used to replace the text within the <text> or <t> element

ROS and cid

are required for Web fonts in OpenType/CFF format
and operate similar to glyphid

13.6 Text on a path

In addition to text drawn in a straight line, SVG also includes the ability to place text
along the shape of a <path> element. The basic algorithm is such that each
glyph is positioned at a specific point on the path, with the glyph
getting rotated such that the baseline of the glyph
is either parallel or tangent to the tangent of the curve at the given point.
Here are some examples of text on a path:

(??? include some drawings here )

The following is a simple example which illustrates many of the basic concepts:

The start-offset attribute defines the distance
from the start of the path where the first character should be
positioned.

Various CSS properties control aspects of text drawn along a path.
The standard set of text and font properties from CSS2 apply,
including 'text-align' and 'vertical-align'.
Additional, the following additional properties control
how the text is formatted and rendered:

text-direction: Possible values are: natural,
which indicates that text advance from character to character
should be dictated by the natural text direction from the font,
l-to-r (text should start toward the beginning ofthe path
and proceed toward the end of the path and the baseline of
the glyphs should be parallel to the path), r-to-l
(text should start at the end of the path and the baseline
of the glyphs should be parallel to the path),
t-to-b (text should start at the beginning of the
path and proceed toward the end of the path and the baseline of
the glyphs should be perpendicular to the path) and b-to-t
(text should start at the end of the path and the baseline
of the glyphs should be parallel to the path),

orient-to-path: Possible values are true
and false, with a default of true. If true, the
glyph/symbol is rotated to have its coordinate system line up
with the tangent of the curve.

text-transform: which defines a transformation
that should be applied (conceptually) after the given glyph/symbol
is properly sized, placed and oriented by all of the other
CSS text properties. The options for this property are the same
as the transform: property (??? add link).

Text on a path opens the possibility of significant implementation
differences due to different methods of calculating distance along
a path. In order to ensure that distance calculations are sufficiently
precise, the following two attributes are available on <path>
elements. (??? Obviously, this section needs to be moved to the
<path> element section.)

flatness= A distance measurement in either
local coordinates or in CSS units which serves as a hint for the allowable error
tolerance allowable in approximating a curve with a series
line segments. Commercial implementations should honor this attribute.

nominal-length= The distance measurement (A)
for the given <path> element computed at authoring time.
The SVG user agent should compute its own distance measurement (B).
The SVG user agent should then scale all distance-along-a-curve
computations by A divided by B.

(??? Insert drawings here)

13.6.1 Vector graphics along a path

SVG's text on a path features set has been generalized to allow
for arbitrary SVG along a path, by adding the use element as a valid child of text.