10 Text

Contents

• 10.1 Introduction
• 10.2 Characters and their corresponding glyphs
• 10.3 Fonts, font tables and baselines
• 10.4 The 'text' element
• 10.5 The 'tspan' element
• 10.6 The 'tref' element
• 10.7 The 'glyphRun' element
• 10.8 Text layout
  • 10.8.1 Text layout introduction
  • 10.8.2 Setting the inline progression direction
  • 10.8.3 Glyph orientation within a text run
  • 10.8.4 Relationship with bidirectionality
• 10.9 Alignment properties
  • 10.9.1 Text alignment properties
  • 10.9.2 Baseline alignment properties
• 10.10 Font selection properties
• 10.11 Spacing properties
• 10.12 Text decoration
• 10.13 Text on a path
  • 10.13.1 Introduction to text on a path
  • 10.13.2 The 'textPath' element
  • 10.13.3 Text on a path layout rules
• 10.14 Alternate glyphs
• 10.15 White space handling
• 10.16 Text selection
• 10.17 DOM interfaces

10.1 Introduction

Text that is to be rendered as part of an SVG document fragment is specified using the 'text' element. The characters to be drawn are expressed as XML character data [XML10] inside the 'text' element.

SVG's 'text' elements are rendered like other graphics elements. Thus, coordinate system transformations, painting, clipping and masking features apply to 'text' elements in the same way as they apply to shapes such as paths and rectangles.

Each 'text' element causes a single string of text to be rendered. SVG performs no automatic line breaking or word wrapping. To achieve the effect of multiple lines of text, use one of the following methods:

• The author or authoring package pre-computes the line breaks and uses multiple 'text' elements (one for each line of text).
• The author or authoring package needs pre-computes the line breaks and uses a single 'text' element with one or more 'tspan' child elements with appropriate values for attributes x, y, dx and dy to set new start positions for those characters which start new lines. (This approach allows user text selection across multiple lines of text -- see Text selection and clipboard operations.)
• Express the text to be rendered in another XML namespace such as XHTML [XHTML] embedded inline within a 'foreignObject' element. (Note: the exact semantics of this approach are not completely defined at this time.)

The text strings within 'text' elements can be rendered in a straight line or rendered along the outline of a 'path' element. SVG supports the following international text processing features for both straight line text and text on a path:

• horizontal and vertical orientation of text
• left-to-right or bidirectional text (i.e., languages which intermix right-to-left and left-to-right text, such as Arabic and Hebrew)
• when SVG fonts are used, automatic selection of the correct glyph corresponding to the current form for Arabic and Han text

Because SVG text is packaged as XML character data [XML10]:

• Text data in SVG content is readily accessible to the visually impaired (see Accessibility Support)
• In many viewing scenarios, the user will be able to search for and select text strings and copy selected text strings to the system clipboard (see Text selection)
• XML-compatible Web search engines will find text strings in SVG content with no additional effort over what they need to do to find text strings in other XML documents

Multi-language SVG content is possible by substituting different text strings based on the user's preferred language.

For accessibility reasons, it is recommended that text which is included in a document have appropriate semantic markup to indicate its function. See SVG accessibility guidelines for more information.
 

10.2 Characters and their corresponding glyphs

In XML [XML10], textual content is defined in terms of a sequence of XML characters, where each character is defined by a particular Unicode code point [UNICODE]. Fonts, on the other hand, consists of a collection of glyphs and other associated information, such as font tables. A glyph is a presentable form of one or more characters (or a part of a character in some cases). Each glyph consists of some sort of identifier (in some cases a string, in other cases a number) along with drawing instructions for rendering that particular glyph.

In many cases, there is a one-to-one mapping of Unicode characters (i.e., Unicode code points) to glyphs in a font. For example, it is common for a font designed for Latin languages (where the term Latin is used for European languages such as English with alphabets similar to and/or derivative to the Latin language) to contain a single glyph for each of the standard ASCII characters (i.e., A-to-Z, a-to-z, 0-to-9, plus the various punctuation characters found in ASCII). Thus, in most situations, the string "XML", which consists of three Unicode characters, would be rendered by the three glyphs corresponding to "X", "M" and "L", respectively.

In various other cases, however, there is not a strict one-to-one mapping of Unicode characters to glyphs. Some of the circumstances when the mapping is not one-to-one:

• Ligatures - For best looking typesetting, it is often desirable that particular sequences of characters are rendered as a single glyph. An example is the word "office". Many fonts will define an "ffi" ligature. When the word "office" is rendered, sometimes the user agent will render the glyph for the "ffi" ligature instead of rendering distinct glyphs (i.e., "f", "f" and "i") for each of the three characters. Thus, for ligatures, multiple Unicode characters map to a single glyph. (Note that for proper rendering of some languages, ligatures are required for certain character combinations.)
• Composite characters - In various situations, commonly used adornments such as diacritical marks will be stored once in a font as a particular glyph and then composed with one or more other glyphs to result in the desired character. For example, it is possible that a font engine might render the é character by first rendering the glyph for e and then rendering the glyph for ´ (the accent mark) such that the accent mark will appear over the e. In this situation, a single Unicode character maps to multiple glyphs.
• Glyph substitution - Some typography systems examine the nature of the textual content and utilize different glyphs in different circumstances. For example, in Arabic, the same Unicode character might render as any of four different glyphs, depending on such factors as whether the character appears at the start, the end or the middle of a sequence of cursively joined characters. Different glyphs might be used for punctuation character depending on inline progression direction (e.g., horizontal vs. vertical). In these situations, a single Unicode character might map to one of several alternative glyphs.
• In some languages, particular sequences of characters will be converted into multiple glyphs such that parts of a particular character are in one glyph and the remainder of that character is in another glyph.
• Alternative glyph specification - SVG contains a facility for the author to explicitly specify that a particular sequence of Unicode characters is to be rendered using a particular glyph. (See Alternate glyphs.) When this facility is used, multiple Unicode characters map to a single glyph.

In many situations, the algorithms for mapping from characters to glyphs are system-dependent, resulting in the possibility that the rendering of text might be (usually slightly) different when viewed in different user environments. If the author of SVG content requires precise selection of fonts and glyphs, then the recommendation is that the necessary fonts (potentially subsetted to include only the glyphs needed for the given document) be available either as SVG fonts embedded within the SVG content or as Web fonts posted at the same Web location as the SVG content.

Throughout this chapter, the term character shall be equivalent to the definition of a character in XML [XML10].

10.3 Fonts, font tables and baselines

A font consists of a collection of glyphs together with the information (the font tables) necessary to use those glyphs to present characters on some medium. The combination of the collection of glyphs and the font tables is called the font data. The font tables include the information necessary to map characters to glyphs, to determine the size of glyph areas and to position the glyph area. Each font table consists of one or more font characteristics, such as the font-weight and font-style.

The geometric font characteristics are expressed in a coordinate system based on the EM box. (The EM is a relative measure of the height of the glyphs in the font; see CSS2 em square.) The box 1 EM high and 1 EM wide is called the design space. This space is given a geometric coordinates by sub-dividing the EM into a number of units-per-em.

Note: Units-per-em is a font characteristic. A typical value for units-per-EM is 1000 or 2048.

The coordinate space of the EM box is called the design space coordinate system. For scalable fonts, the curves and lines that are used to draw a glyph are represented using this coordinate system.

Note: Most often, the (0,0) point in this coordinate system is positioned on the left edge of the EM box, but not at the bottom left corner. The Y coordinate of the bottom of a roman capital letter is usually zero. And the descenders on lower case roman letters have negative coordinate values.

SVG assumes that the font tables will provide at least three font characteristics: an ascent, a descent and a set of baseline-tables. The ascent is the distance to the top of the EM box from the (0,0) point of the font; the descent is the distance to the bottom of the EM box from the (0.0) point of the font. The baseline-table is explained below.

Note: Within an OpenType font, for horizontal writing-modes, the ascent and descent are given by the sTypoAscender and sTypoAscender entries in the OS/2 table. For vertical writing-modes, the descent (the distance, in this case from the (0,0) point to the left edge of the glyph) is normally zero because the (0,0) point is on the left edge. The ascent for vertical writing-modes is either 1 em or is specified by the Ideographic top baseline value in the OpenType Base table for vertical writing-modes.

In horizontal writing-modes, the glyphs of a given script are positioned so that a particular point on each glyph, the alignment-point, is aligned with the alignment-points of the other glyphs in that script. The glyphs of different scripts, for example, western, northern indic and far-eastern scripts, are typically aligned at different points on the glyph. For example, western glyphs are aligned on the bottoms of the capital letters, northern indic glyphs are aligned at the top of a horizontal stroke near the top of the glyphs and far-eastern glyphs are aligned either at the bottom or center of the glyph. Within a script and within a line of text having a single font-size, the sequence of alignment-points defines, in the inline- progression-direction, a geometric line called a baseline. Western and most other alphabetic and syllabic glyphs are aligned to an "alphabetic" baseline, the northern indic glyphs are aligned to a "hanging" baseline and the far-eastern glyphs are aligned to an "ideographic" baseline.

A baseline-table specifies the position of one or more baselines in the design space coordinate system. The function of the baseline table is to facilitate the alignment of different scripts with respect to each other when they are mixed on the same text line. Because the desired relative alignments may depend on which script is dominant in a line (or block), there may be a different baseline table for each script. In addition, different alignment positions are needed for horizontal and vertical writing modes. Therefore, the font may have a set of baseline tables: typically, one or more for horizontal writing-modes and zero or more for vertical writing-modes.

Note: Some fonts may not have values for the baseline tables. Heuristics are suggested for approximating the baseline tables when a given font does not supply baseline tables.

SVG further assumes that for each glyph in the font data for a font, there is are two width values, two alignment-baselines and two alignment-points, one each for horizontal writing-modes and the other for vertical writing-modes. (Even though it is specified as a width, for vertical writing-modes the width is used in the vertical direction.) The script to which a glyph belongs determines an alignment-baseline to which the glyph is to be aligned. The inline-progression-direction position of the alignment-point is on the start-edge of the glyph.

Properties related to baselines are described below under Baseline alignment properties.

In addition to the font characteristics required above, a font may also supply substitution and positioning tables that can be used by a formatter to re-order, combine and position a sequence of glyphs to make one or more composite glyphs. The combination may be as simple as a ligature, or as complex as an indic syllable which combines, usually with some re-ordering, multiple consonants and vowel glyphs.

10.4 The 'text' element

The 'text' element defines a graphics element consisting of text. The XML [XML10] character data within the 'text' element, along with relevant attributes and properties and character-to-glyph mapping tables within the font itself, define the glyphs to be rendered. (See Characters and their corresponding glyphs.) The attributes and properties on the 'text' element indicate such things as the writing direction, font specification and painting attributes which describe how exactly to render the characters. Subsequent sections of this chapter describe the relevant text-specific attributes and properties, particular text layout and bidirectionality.

Since 'text' elements are rendered using the same rendering methods as other graphics elements, all of the same coordinate system transformations, painting, clipping and masking features that apply to shapes such as paths and rectangles also apply to 'text' elements.

It is possible to apply a gradient, pattern, clipping path, mask or filter to text. When one of these facilities is applied to text and keyword objectBoundingBox is used (see Object bounding box units) to specify a graphical effect relative to the "object bounding box", then the object bounding box units are computed relative to the entire 'text' element in all cases, even when different effects are applied to different 'tspan' elements within the same 'text' element.

The 'text' element renders its first glyph (after bidirectionality reordering) at the initial current text position, which is established by the x and y attributes on the 'text' element (with possible adjustments due to the value of the 'text-anchor' property, the presence of a 'textPath' element containing the first character, and/or an x, y, dx or dy attributes on a 'tspan', 'tref' or 'glyphRun' element which contains the first character). After the glyph(s) corresponding to the given character is(are) rendered, the current text position is updated for the next character. In the simplest case, the new current text position is the previous current text position plus the glyphs' advance value (horizontal or vertical). See text layout for a description of glyph placement and glyph advance.

<!ENTITY % textExt "" >
<!ELEMENT text (#PCDATA|desc|title|metadata|
                tspan|tref|textPath|altGlyph|a|animate|set|
                animateMotion|animateColor|animateTransform
                %geExt;%textExt;)* >
<!ATTLIST text
  %stdAttrs;
  %testAttrs;
  %langSpaceAttrs;
  externalResourcesRequired %Boolean; #IMPLIED
  class %ClassList; #IMPLIED
  style %StyleSheet; #IMPLIED
  %PresentationAttributes-FillStroke;
  %PresentationAttributes-FontSelection;
  %PresentationAttributes-Graphics;
  %PresentationAttributes-TextContentElements;
  %PresentationAttributes-TextElements;
  transform %TransformList; #IMPLIED
  %graphicsElementEvents;
  x %Coordinate; #IMPLIED
  y %Coordinate; #IMPLIED
  textLength %Length; #IMPLIED
  lengthAdjust (spacing|spacingAndGlyphs) #IMPLIED >

Example text01 below expresses all values in physical units such as centimeters and points. The 'text' element contains the text string "Hello, out there" which will be rendered onto the canvas using the Verdana font family with font size of 12 points with the glyphs filled with the color blue.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000802//EN" 
  "http://www.w3.org/TR/2000/CR-SVG-20000802/DTD/svg-20000802.dtd">
<svg width="10cm" height="3cm">
  <desc>Example text01 - 'Hello, out there' in blue</desc>

  <text x="2.5cm" y="1.5cm" 
        style="font-family:Verdana; font-size:16pt; fill:blue">
    Hello, out there
  </text>
</svg>

Example text01

View this example as SVG (SVG-enabled browsers only)
 

Example text02 below expresses the x and y attributes and the 'font-size' property in the user coordinate system set up by the viewBox attribute on the 'svg' element. The 'text' element contains the text string "Text in user space."

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000802//EN" 
  "http://www.w3.org/TR/2000/CR-SVG-20000802/DTD/svg-20000802.dtd">
<svg width="10cm" height="3cm" viewBox="0 0 1000 300">
  <desc>Example text02 - Text in user space</desc>

  <text x="250" y="150" 
        style="font-family:Verdana; font-size:42.333; fill:blue">
    Text in user space
  </text>
</svg>

Example text02

View this example as SVG (SVG-enabled browsers only)
 

10.5 The 'tspan' element

Within a 'text' element, text and font properties and the current text position can be adjusted with absolute or relative coordinate values by including a 'tspan' element.

<!ENTITY % tspanExt "" >
<!ELEMENT tspan (#PCDATA|desc|title|metadata|tspan|tref|altGlyph|a|animate|set|animateColor
                %tspanExt;)* >
<!ATTLIST tspan
  %stdAttrs;
  %testAttrs;
  %langSpaceAttrs;
  externalResourcesRequired %Boolean; #IMPLIED
  class %ClassList; #IMPLIED
  style %StyleSheet; #IMPLIED
  %PresentationAttributes-FillStroke;
  %PresentationAttributes-FontSelection;
  %PresentationAttributes-Graphics;
  %PresentationAttributes-TextContentElements;
  %graphicsElementEvents;
  x %Coordinates; #IMPLIED
  y %Coordinates; #IMPLIED
  dx %Lengths; #IMPLIED
  dy %Lengths; #IMPLIED
  rotate CDATA #IMPLIED
  textLength %Length; #IMPLIED
  lengthAdjust (spacing|spacingAndGlyphs) #IMPLIED >

The x, y, dx, dy and rotate on the 'tspan' element are useful in high-end typography scenarios where individual glyphs require exact placement. These attributes are useful for minor positioning adjustments between characters or for major positioning adjustments, such as moving the current text position to a new location to achieve the visual effect of a new line of text. Multi-line 'text' elements are possible by defining different 'tspan' elements for each line of text, with attributes x, y, dx and/or dy defining the position of each 'tspan'. (An advantage of such an approach is that users will be able to perform multi-line text selection.)

In situations where micro-level positioning adjustment are necessary for advanced typographic control, the SVG content designer needs to ensure that the necessary font will be available for all viewers of the document (e.g., package up the necessary font data in the form of an SVG font or an alternative Web font format which is stored at the same Web site as the SVG content) and that the viewing software will process the font in the expected way (the capabilities, characteristics and font layout mechanisms vary greatly from system to system). If the SVG content contains x, y, dx or dy attribute values which are meant to correspond to a particular font processed by a particular set of viewing software and either of these requirements is not met, then the text might display with poor quality.

The following additional rules apply to attributes x, y, dx, dy and rotate when they contain a list of numbers:

• When a single XML character maps to a single glyph - In this case, the i-th value for the x, y, dx, dy and rotate attributes is applied to the glyph that corresponds to the i-th character.
• When a single XML character maps to multiple glyphs (e.g., when an accent glyph is placed on top of a base glyph) - In this case, the i-th value for the x, y, dx and dy values are applied (i.e., the current text position is adjusted) before rendering the first glyph. The rotation transformation corresponding to the i-th rotate value is applied to the glyphs and to the inter-glyph advance values corresponding to this character on a group basis (i.e., the rotation value creates a temporary new rotated coordinate system, and the glyphs corresponding to the character are rendered into this rotated coordinate system).
• When multiple XML characters map to a single glyph (e.g., when a ligature is used) - Suppose that the i-th and (i+1)-th XML characters map to a single glyph. In this case, the i-th value for the x, y, dx, dy and rotate attributes all apply when rendering the glyph. The (i+1)-th values, however, for x, y and rotate are ignored (exception: the final rotate value in the list would still apply to subsequent characters), whereas the dx and dy are applied to the subsequent XML character (i.e., the (i+2)-th character), if one exists, by translating the current text position by the given amounts before rendering the first glyph associated with that character.
• When there is a many-to-many mapping of characters to glyphs (e.g., when three characters map to two glyphs, such as when the first glyph expresses the first character and half of the second character, and the second glyph expresses the other half of the second character plus the third character) - Suppose that the i-th, (i+1)-th and (i+2)-th XML characters map to two glyphs. In this case, the i-th value for the x, y, dx and dy values are applied (i.e., the current text position is adjusted) before rendering the first glyph. The rotation transformation corresponding to the i-th rotate value is applied to both the two glyphs and the glyph advance values for the first glyph on a group basis (i.e., the rotation value creates a temporary new rotated coordinate system, and the two glyphs are rendered into the temporary rotated coordinate system). The (i+1)-th and (i+2)-th values, however, for the x, y and rotate attributes are not applied (exception: the final rotate value in the list would still apply to subsequent characters), whereas the (i+1)-th and (i+2)-th values for the dx and dy attributes are applied to the subsequent XML character (i.e., the (i+3)-th character), if one exists, by translating the current text position by the given amounts before rendering the first glyph associated with that character.
• Relationship to bidirectionality - As described below in the discussion on bidirectionality, text is laid out in a two-step process, where any bidirectional text is first re-ordered into a left-to-right string, and then text layout occurs with the re-ordered text string. Whenever the character data within a 'tspan' element is re-ordered, the corresponding elements within the x, y, dx, dy and rotate are also re-ordered to maintain the correspondence. For example, suppose that you have the following 'tspan' element:

  <tspan dx="11 12 13 14 15 0 21 22 23 0 31 32 33 34 35 36">Latin and Hebrew</span>
  

  and that the word "Hebrew" will be drawn right-to-left. First, the character data and the corresponding values in the dx list will be reordered, such that the text string will be "Latin and werbeH" and the list of values for the dx attribute will be "11 12 13 14 15 0 21 22 23 0 36 35 34 33 32 31". After this re-ordering, the glyphs corresponding to the characters will be positioned using standard left-to-right layout rules.
• Nested 'tspan' elements - The x, y, dx, dy and rotate attributes on a given 'tspan' element apply only to the character data that is directly within that 'tspan' element and do not apply to the character data within child (i.e., nested) 'tspan' elements. If the nested 'tspan' elements require positioning adjustments or rotation values, the nested 'tspan' elements need to specify x, y, dx, dy and rotate values for their own character data.

The following examples show basic use of the 'tspan' element.

Example tspan01 uses a 'tspan' element to indicate that the word "not" is to use a bold font and have red fill.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000802//EN" 
  "http://www.w3.org/TR/2000/CR-SVG-20000802/DTD/svg-20000802.dtd">
<svg width="10cm" height="3cm">
  <desc>Example tspan01 - using tspan to change visual attributes</desc>

  <g style="font-family:Verdana; font-size:12pt">
    <text x="2cm" y="1.5cm" style="fill:blue">
      You are
        <tspan style="font-weight:bold; fill:red">not</tspan>
      a banana.
    </text>
  </g>
</svg>

Example tspan01

View this example as SVG (SVG-enabled browsers only)
 

Example tspan02 uses the dx and dy attributes on the 'tspan' element to adjust the current text position horizontally and vertically for particular text strings within a 'text' element.

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000802//EN" 
  "http://www.w3.org/TR/2000/CR-SVG-20000802/DTD/svg-20000802.dtd">
<svg width="10cm" height="3cm">
  <desc>Example tspan02 - using tspan's dx and dy attributes 
        for incremental positioning adjustments</desc>

  <g style="font-family:Verdana; font-size:12pt">
    <text x="2cm" y="1.5cm" style="fill:blue">
      But you
        <tspan dx="2em" dy="-.5cm" style="font-weight:bold; fill:red">
          are
        </tspan>
        <tspan dy="1cm">
           a peach!
        </tspan>
    </text>
  </g>
</svg>

Example tspan02

View this example as SVG (SVG-enabled browsers only)
 

Example tspan03 uses the x and y attributes on the 'tspan' element to establish a new absolute current text position for each glyph to be rendered. The example shows two lines of text within a single 'text' element. Because both lines of text are within the same 'text' element, the user will be able to select through both lines of text and copy the text to the system clipboard in user agents that support text selection and clipboard operations,

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000802//EN" 
  "http://www.w3.org/TR/2000/CR-SVG-20000802/DTD/svg-20000802.dtd">
<svg width="10cm" height="3cm">
  <desc>Example tspan03 - using tspan's x and y attributes 
        for multiline text and precise glyph positioning</desc>

  <g style="font-family:Verdana; font-size:12pt">
    <text style="fill:rgb(255,164,0)">
      <tspan x="3.0cm 3.5cm 4.0cm 4.5cm 5.0cm 5.5cm 6.0cm 6.5cm" y="1cm">
        Cute and
      </tspan>
      <tspan x="3.75cm 4.25cm 4.75cm 5.25cm 5.75cm" y="2cm">
         fuzzy
      </tspan>
    </text>
  </g>
</svg>

Example tspan03

View this example as SVG (SVG-enabled browsers only)
 

10.6 The 'tref' element

The textual content for a 'text' can be either character data directly embedded within the 'text' element or the character data content of a referenced element, where the referencing is specified with a 'tref' element.

<!ENTITY % trefExt "" >
<!ELEMENT tref (desc|title|metadata|animate|set|animateColor
                %trefExt;)* >
<!ATTLIST tref
  %stdAttrs;
  %xlinkRefAttrs;
  xlink:href %URI; #REQUIRED
  %testAttrs;
  %langSpaceAttrs;
  externalResourcesRequired %Boolean; #IMPLIED
  class %ClassList; #IMPLIED
  style %StyleSheet; #IMPLIED
  %PresentationAttributes-FillStroke;
  %PresentationAttributes-FontSelection;
  %PresentationAttributes-Graphics;
  %PresentationAttributes-TextContentElements;
  %graphicsElementEvents;
  x %Coordinates; #IMPLIED
  y %Coordinates; #IMPLIED
  dx %Lengths; #IMPLIED
  dy %Lengths; #IMPLIED
  rotate CDATA #IMPLIED
  textLength %Length; #IMPLIED
  lengthAdjust (spacing|spacingAndGlyphs) #IMPLIED >

All character data within the referenced element, including character data enclosed within additional markup, will be rendered.

The x, y, dx, dy and rotate attributes have the same meanings as for the 'tspan' element. The attributes are applied as if the 'tref' element was replaced by a 'tspan' with the referenced character data (stripped of all supplemental markup) embedded within the hypothetical 'tspan' element.

Example tref01 shows how to use character data from a different element as the character data for a given 'tspan' element. The first 'text' element (with id="ReferencedText") will not draw because it is part of a 'defs' element. The second 'text' element draws the string "Inline character data". The third 'text' element draws the string "Reference character data" because it includes a 'tref' element which is a reference to element "ReferencedText", and that element's character data is "Referenced character data".

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 20000802//EN" 
  "http://www.w3.org/TR/2000/CR-SVG-20000802/DTD/svg-20000802.dtd">
<svg width="10cm" height="3cm">
  <defs>
    <text id="ReferencedText">
      Referenced character data
    </text>
  </defs>
  <desc>Example tref01 - inline vs reference text content</desc>

  <text x="1cm" y="1cm" style="font-size:12pt; fill:blue">
    Inline character data
  </text>
  <text x="1cm" y="2cm" style="font-size:12pt; fill:red">
    <tref xlink:href="#ReferencedText"/>
  </text>
</svg>

Example tref01

View this example as SVG (SVG-enabled browsers only)
 

10.7 The 'glyphRun' element

The 'glyphRun' element provides a way for presenting text as a sequence of particular glyphs from a particular font, which can be used by authoring tools to guarantee correct glyph selection and ordering for the text strings in languages with complex Unicode-to-glyph mapping rules. With 'glyphRun', the glyphs are rendered in exactly the order which has been specified by attribute glyphOrder.

The contents of a 'glyphRun' element are a sequence of 'altGlyph' child elements. The Unicode character data contents of the 'altGlyph' represent the text data in selection and searching order, and the referenced 'altGlyphDef' elements indicate the specific font and glyph combinations to use for rendering that character data. The glyphOrder attribute allows the glyphs to be rendered in a different order.

Properties 'direction' and 'unicode-bidi' are ignored during processing of a 'glyphRun' element. No character re-ordering (see Relationship with bidirectionality) occurs for the content of a 'glyphRun' element.

<!ENTITY % glyphRunExt "" >
<!ELEMENT glyphRun (#PCDATA|desc|title|metadata|altGlyph|a|animate|set|animateColor
                %glyphRunExt;)* >
<!ATTLIST glyphRun
  %stdAttrs;
  %testAttrs;
  %langSpaceAttrs;
  externalResourcesRequired %Boolean; #IMPLIED
  class %ClassList; #IMPLIED
  style %StyleSheet; #IMPLIED
  %PresentationAttributes-FillStroke;
  %PresentationAttributes-FontSelection;
  %PresentationAttributes-Graphics;
  %PresentationAttributes-TextContentElements;
  %graphicsElementEvents;
  x %Coordinates; #IMPLIED
  y %Coordinates; #IMPLIED
  dx %Lengths; #IMPLIED
  dy %Lengths; #IMPLIED
  rotate CDATA #IMPLIED
  glyphOrder CDATA #IMPLIED
  textLength %Length; #IMPLIED
  lengthAdjust (spacing|spacingAndGlyphs) #IMPLIED >

To illustrate with an example:

<altGlyphDef id="Glyph1">....</altGlyphDef>
<altGlyphDef id="Glyph2">....</altGlyphDef>
<text>
  <glyphRun x="20 30" y="10 10" glyphIndices="2 1">
    <altGlyph xlink:href="Glyph1">A</altGlyph>
    <altGlyph xlink:href="Glyph2">b</altGlyph>
  </glyphRun>
</text>

The result will be that Glyph2 will be rendered at (20,10), and then Glyph1 will be rendered at (30,10).

All white space within a 'glyphRun' that is not part of an 'altGlyph' will be ignored.

The value of 'writing-mode' determines whether glyph advance is left-to-right, right-to-left or top-to-bottom.

For text selection, when you copy selection to the clipboard, you get the Unicode code points specified inside of the 'altGlyph' elements.

If any of the 'altGlyph' elements has no character data content within it, then it is assumed to correspond to the previous sibling 'altGlyph' which has character data content (i.e., multiple glyphs for a single character). (In this case, it is recommended that user agents do not allow text selection operations to select between glyphs that map to the same character data content.) If there is no previous sibling with character data content, then that 'altGlyph' has no corresponding character data content.

10.8 Text layout

10.8.1 Text layout introduction

This section describes the text layout features supported by SVG, which includes support for various international writing directions, such as left-to-right (e.g., Latin scripts) and bidirectional (e.g., Hebrew or Arabic) and vertical (e.g., Asian scripts). The descriptions in this section assume straight line text (i.e., text that is either strictly horizontal or vertical with respect to the current user coordinate system). Subsequent sections describe the supplemental layout rules for text on a path.

SVG does not provide for automatic line breaks or word wrapping, which makes internationalized text layout for SVG relatively simpler than it is for languages which support formatting of multi-line text blocks.

For each 'text' element, the SVG user agent determines the current reference orientation. For standard horizontal or vertical text (i.e., no text-on-a-path), the reference orientation is the vector pointing towards negative infinity in Y within the current user coordinate system. (Note: in the initial coordinate system, the reference orientation is up.) For text on a path, the reference orientation is reset with each character.

Based on the reference orientation and the value for property 'writing-mode', the SVG user agent determines the current inline progression direction. For left-to-right text, the inline progression direction points 90 degrees clockwise from the reference orientation vector. For right-to-left text, the inline progression points 90 degrees counter-clockwise from the reference orientation vector. For top-to-bottom text, the inline progression direction points 180 degrees from the reference orientation vector.

The shift direction is the direction towards which the baseline table moves due to positive values for property 'baseline-shift'. The shift direction is such that a positive value shifts the baseline table towards the topmost entry in the parent's baseline table.

In processing a given 'text' element, the SVG user agent keeps track of the current text position. The initial current text position is established by the x and y attributes on the 'text' element.

The current text position is adjusted after each glyph to establish a new current text position at which the next glyph shall be rendered. The adjustment to the current text position is based on the current inline progression direction, glyph-specific advance values corresponding to the glyph orientation of the glyph just rendered, kerning tables in the font and the current values of various attributes and properties, such as the spacing properties and any x, y, dx and dy attributes on 'tspan', 'tref' or 'glyphRun' elements. If a glyph does not provide explicit advance values corresponding to the current glyph orientation, then an appropriate approximation should be used. For vertical text, a suggested approximation is the sum of the ascent and descent values for the glyph. Another suggested approximation for an advance value for both horizontal and vertical text is the size of an em (see units-per-em).

For each glyph to be rendered, the SVG user agent determines an appropriate alignment-point on the glyph which will be placed exactly at the current text position. The alignment-point is determined based on glyph cell metrics in the glyph itself, the current inline progression direction and the glyph orientation relative to the inline progression direction. For most uses of Latin text (i.e., 'writing-mode:lr', 'text-anchor:start', and 'alignment-baseline:baseline') the alignment-point in the glyph will be the intersection of left edge of the glyph cell (or some other glyph-specific x-axis coordinate indicating a left-side origin point) with the Latin baseline of the glyph. For many cases with top-to-bottom vertical text layout, the reference point will be either a glyph-specific origin point based on the set of vertical baselines for the font or the intersection of the center of the glyph with its top line (see [CSS2] for a definition of top line). If a glyph does not provide explicit origin points corresponding to the current glyph orientation, then an appropriate approximation should be used, such as the intersection of the left edge of the glyph with the appropriate horizontal baseline for the glyph or intersection of the top edge of the glyph with the appropriate vertical baseline. If baseline tables are not available, user agents should establish baseline tables that reflect common practice.

Adjustments to the current text position are either absolute position adjustments or relative position adjustments. An absolute position adjustment occurs in the following circumstances:

• At the start of a 'text' element
• At the start of each 'textPath' element
• For each character within a 'tspan', 'tref' and 'glyphRun' element which has an x or y attribute value assigned to it explicitly

All other position adjustments to the current text position are relative position adjustments.

Each absolute position adjustment defines a new text chunk. Absolute position adjustments impact text layout in the following ways:

• Ligatures only occur when a set of characters which might map to a ligature are all in the same text chunk.
• Each text chunk represents a separate block of text for alignment due to 'text-anchor' property values.
• Reordering of characters due to bidirectionality only occurs within a text chunk. Reordering does not happen across text chunks.

10.8.2 Setting the inline progression direction

The 'writing-mode' property specifies whether the initial inline progression direction for a 'text' element shall be left-to-right, right-to-left, or top-to-bottom. The 'writing-mode' property applies only to 'text' elements; the property is ignored for 'tspan', 'tref', 'glyphRun' and 'textPath' sub-elements. (Note that the inline progression direction can change within a 'text' element due to the Unicode bidirectional algorithm and properties 'direction' and 'unicode-bidi'. For more on bidirectional text, see Relationship with bidirectionality.)

lr-tb | lr

Sets the initial inline progression direction to left-to-right, as is common in most Latin-based documents. For most characters, the current text position is advanced from left to right after each glyph is rendered. (When the character data includes characters which are subject to the Unicode bidirectional algorithm, the text advance rules are more complex. See Relationship with bidirectionality).

rl-tb | rl

Sets the initial inline progression direction to right-to-left, as is common in Arabic or Hebrew scripts. (See Relationship with bidirectionality.)

tb-rl | tb

Sets the initial inline progression direction to top-to-bottom, as is common in Asian scripts. Though hardly as frequent as horizontal, this type of vertical layout also occurs in Latin based documents, particularly in table column or row labels. In most cases, the vertical baselines running through the middle of each glyph are aligned.

10.8.3 Glyph orientation within a text run

In some cases, it is required to alter the orientation of a sequence of characters relative to the inline progression direction. The requirement is particularly applicable to vertical layouts of East Asian documents, where sometimes narrow-cell Latin text is to be displayed horizontally and other times vertically.

Two properties control the glyph orientation relative to the reference orientation for each of the two possible inline progression directions. 'glyph-orientation-vertical' controls glyph orientation when the inline progression direction is vertical. 'glyph-orientation-horizontal' controls glyph orientation when the inline progression direction is horizontal.

<angle>

The value of the angle is an <integer> restricted to the range of -360 to +360 in 90-degree increments.
A value of 0 indicates that all glyphs are unrotated relative to the reference orientation, resulting in glyphs which are stacked vertically on top of each other. A value of 90 indicates a rotation of 90 degrees clockwise relative to the reference orientation. Negative angle values are computed modulo 360; thus, a value of -90 is equivalent to a value of 270.

auto

The glyph orientation relative to the inline progression direction is determined automatically based on the Unicode character number of the first rendered glyph.

Full-width ideographic and full-width Latin glyphs (excluding ideographic punctuation) are oriented as if an <angle> of "0" had been specified (i.e., glyphs are unrotated relative to the reference orientation, resulting in glyphs which are stacked vertically on top of each other).

Ideographic punctuation and other ideographic glyphs having alternate horizontal and vertical forms shall use the vertical form of the glyph.

Text which is not full-width will be set as if an <angle> of "90" had been specified; thus, narrow-cell Latin text will be rotated 90 degree clockwise versus full-width ideographic and full-width Latin text.

Note that a value of auto will generally produce the expected results in common uses of mixing Japanese with European characters; however, the exact algorithms are based on complex interactions between many factors, including font design, and thus different algorithms might be employed in different processing environments. For precise control, specify explicit <angle> values.

Glyphs corresponding to Arabic or Hebrew characters that are not full-width have the same orientation as narrow-cell Latin.

The glyph orientation affects the amount that the current text position advances as each glyph is rendered. When the inline progression direction is vertical and the 'glyph-orientation-vertical' results in an orientation angle that is a multiple of 180 degrees, then the current text position is incremented according to the vertical metrics of the glyph. Otherwise, if the 'glyph-orientation-vertical' results in an orientation angle that is not a multiple of 180 degrees, then the current text position is incremented according to the horizontal metrics of the glyph.

The text layout diagrams in this section use the following symbols:

- wide-cell glyph (e.g. Han) which is the n-th glyph in the text run
- narrow-cell glyph (e.g. Latin) which is the n-th glyph in the text run

The orientation which the above symbols assume in the diagrams corresponds to the orientation that the Unicode characters they represent are intended to assume when rendered in the user agent. Spacing between the glyphs in the diagrams is usually symbolic, unless intentionally changed to make a point.

The diagrams below illustrate different uses of 'glyph-orientation-vertical'. The diagram on the left shows the result of the mixing of full-width ideographic glyphs with narrow-cell Latin glyphs when 'glyph-orientation-vertical' for the Latin characters is either auto or 90. The diagram on the right show the result of mixing full-width ideographic glyphs with narrow-cell Latin glyphs when Latin glyphs are specified to have a 'glyph-orientation-vertical' of 0.

<angle>

The value of the angle is an <integer> restricted to the range of -360 to +360 in 90-degree increments.
A value of 0 indicates that all glyphs are unrotated with respect to the reference orientation, resulting in glyphs which are positioned side by side. A value of 90 indicates an orientation of 90 degrees clockwise from the reference orientation. Angle values are computed modulo 360; thus, a value of -90 is equivalent to a value of 270.

The glyph orientation affects the amount that the current text position advances as each glyph is rendered. When the reference orientation direction is horizontal and the 'glyph-orientation-horizontal' results in an orientation angle that is a multiple of 180 degrees, then the current text position is incremented according to the horizontal metrics of the glyph. Otherwise, if the 'glyph-orientation-vertical' results in an orientation angle that is not a multiple of 180 degrees, then the current text position is incremented according to the vertical metrics of the glyph.