/
text.html
6773 lines (6126 loc) · 253 KB
/
text.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional+edit//EN" "xhtml1-transitional+edit.dtd">
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xmlns:edit="http://xmlns.grorg.org/SVGT12NG/">
<head>
<title>Text</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"/>
<!-- Style sheets for local dev. Will be standardized in processing.
Add attribute data-keep="" to any extra stylesheet link you do not want removed
(or use <style>), and include it before here. -->
<link rel="stylesheet" href="style/svg.css" type="text/css" />
<link rel="stylesheet" href="style/W3C-ED.css" type="text/css" />
</head>
<body>
<h1>Text</h1>
<h2 id="Introduction">Introduction</h2>
<p>
Text that is to be rendered as part of an SVG document fragment is
specified using the <a>'text'</a> element. The text within a
<a>'text'</a> element can be rendered:
</p>
<ul>
<li>pre-formatted (with limited line wrapping),</li>
<li>auto-wrapped (if a <a>content area</a> is provided),</li>
<li>on a path (if a <a>'textPath'</a> element is provided).</li>
</ul>
<p>
The section <a href="text.html#TextLayout">Text layout</a> gives an
introduction to text layout. It is followed by sections covering
<a href="text.html#TextLayoutContentArea">content areas</a> and
the <a href="text.html#TextLayoutAlgorithm">algorithm</a> for
laying out text within a <a>content area</a>.
The specialized layout rules corresponding to text that is
<a href="text.html#TextLayoutPre">pre-formatted</a>,
<a href="text.html#TextLayoutAuto">auto-wrapped</a>, and
<a href="text.html#TextLayoutPath">on a path</a>
are then addressed in individual sections.
</p>
<p class="note">
Rules for text layout in SVG 1.1 are mostly defined within the SVG
1.1 specification. The rules mirror to a large extent those found
in CSS. In SVG 2, the dependence on CSS is more explicit. In
practice the resulting layout is the same. The change to directly
relying on CSS specifications simplifies the SVG specification
while making it more obvious that rendering agents can use the
same code to render both text in HTML and in SVG. In particular,
SVG 2 auto-wrapped text is based on CSS text layout.
</p>
<p>
SVG's <a>'text'</a> elements are rendered like other graphics
elements. Thus, <a href="coords.html">coordinate system
transformations</a>, <a href="painting.html">painting</a>,
<a href="render.html#ClippingAndMasking">clipping</a> and
<a href="render.html#ClippingAndMasking">masking</a> features apply to
<a>'text'</a> elements in the same way as they apply to
<a>shapes</a> such as
<a href="paths.html">paths</a> and <a href="shapes.html#RectElement">rectangles</a>.
</p>
<p>
SVG text supports advanced typographic features including:
</p>
<ul>
<li>choice of typeface,</li>
<li>use of discretionary, historical, or stylistic ligatures,</li>
<li>text decorations (underlining, over-lining, etc.).</li>
</ul>
<p>
SVG text supports international text processing needs such as:
</p>
<ul>
<li>horizontal and vertical orientation of text,</li>
<li>left-to-right or bidirectional text (i.e., languages
which intermix right-to-left and left-to-right text, such as
Arabic and Hebrew),</li>
<li>
complex text layout where: there is not always a one-to-one
correspondence between characters and glyphs, characters
may change shape depending on location (e.g. Arabic), and
characters may be reordered or combined depending on context
(e.g. Devanagari),
</li>
<li>
glyph alignment to different baselines (<em>alphabetic</em> for
western scripts, <em>hanging</em> for northern indic scripts,
and <em>ideographic</em> for far-eastern scripts).
</li>
</ul>
<p>
Multi-language SVG content is possible by
<a href="struct.html#SwitchElement">substituting different
text strings based on the user's preferred language</a>.
</p>
<p>
The characters to be drawn are expressed as
<a href="https://www.w3.org/TR/2008/REC-xml-20081126/#syntax">character data</a> ([<a href="refs.html#ref-xml">xml</a>],
section 2.4) inside the <a>'text'</a> element. As a result:
</p>
<ul>
<li>
Text data in SVG content is readily accessible to the visually
impaired (see <a href="access.html">Accessibility
Support</a>).
</li>
<li>
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 <a href="text.html#TextSelection">Text
selection and clipboard operations</a>).
</li>
<li>
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.
</li>
</ul>
<p>
For accessibility reasons, it is recommended that text that is
included in a document have appropriate semantic markup to
indicate its function.
For example,
a text element that provides a visible label for part of a diagram
should have an <a>'id'</a> that is referenced by
an <a>'aria-labelledby'</a> attribute on the relevant group or path element.
See <a href="access.html">SVG
accessibility guidelines</a> for more information.
</p>
<h3 id="Definitions">Definitions</h3>
<dl class="definitions">
<dt><dfn id="TermCharacter" data-dfn-type="dfn" data-export="">character</dfn></dt>
<dd>
A character is an atomic unit of text as defined in XML
[<a href="https://www.w3.org/TR/2008/REC-xml-20081126/">XML</a>].
<p class="note">
Essentially, a Unicode code point.
A character may be a control instruction (such as a tab, carriage return, or line feed),
a renderable mark (letter, digit, punctuation or other symbol),
or a modifier (such as a combining accent).
</p>
</dd>
<dt><dfn id="TermAddressableCharacter" data-dfn-type="dfn" data-export="">addressable character</dfn></dt>
<dd>
A <a>character</a> that is addressable by text positioning
attributes and SVG DOM text methods.
Characters discarded during layout such as
<a href="https://www.w3.org/TR/css-text-3/#white-space-phase-1">collapsed
white space characters</a> are not addressable, neither are characters
within an element with a value of <span class='prop-value'>none</span> for
the <a>'display'</a> property.
Addressable characters are addressed by their index measured in UTF-16 code units
(thus, a single Unicode code point above U+FFFF will map to two addressable characters as
a UTF-16 code unit consists of 16 bits).
Indexes are determined prior to applying any <a>'text-transform'</a> conversions,
as described for the methods in the <a>SVGTextContentElement</a> interface.
<p class="note">
If support for CSS generated-content text is introduced in the future,
it would be included in the array of addressable characters.
</p>
</dd>
<dt id="TermTypographicCharacterUnit">typographic character</dt>
<dd>
A unit of a writing system— such as a Latin alphabetic letter
(including its diacritics), Hangul syllable, Chinese ideographic
character, Myanmar syllable cluster— that is indivisible with
respect to a particular typographic operation (line-breaking,
first-letter effects, tracking, justification, vertical
arrangement, etc.). For the normative definition and the
relationship between this and a Unicode grapheme cluster, see
<a href="https://drafts.csswg.org/css-text-3/#typographic-character-unit">CSS
Text Module Level 3</a>,
([<a href="refs.html#ref-css-text-3">css-text-3</a>]).
</dd>
<dt id="TermFont">font</dt>
<dd>
A font represents an organized collection of <a>glyphs</a> in
which the various glyph representations will share a particular
appearance or styling.
</dd>
<dt id="TermGlyph">glyph</dt>
<dd>
A glyph represents a unit of rendered content within a
<a>font</a>. Often, there is a one-to-one correspondence between
characters to be drawn and corresponding glyphs (e.g., usually
the character "A" is rendered using a single glyph), but other
times multiple glyphs are used to render a single character
(e.g., characters with accents) or a single glyph can be used to render
multiple characters (e.g., ligatures). Typically, a glyph is
defined by one or more <a>shapes</a> such as
a <a href="paths.html">path</a>, possibly with additional
information such as rendering hints that help a font engine to
produce legible text in small sizes.
</dd>
<dt><dfn id="TermTextContentElement" data-dfn-type="dfn" data-export="">text content element</dfn></dt>
<dd>
A text content element is an SVG element that causes a text
string to be rendered onto the canvas. The SVG text content
elements are:
<edit:elementcategory name='text content'/>.
</dd>
<dt id="TermTextContentChildElement">text content child element</dt>
<dd>
A text content child element is a <a>text content element</a>
that is allowed as a descendant of another <a>text content
element</a>. In SVG the text content child elements are:
<edit:elementcategory name='text content child'/>.
</dd>
<dt id="TermTextContentBlockElement">text content block element</dt>
<dd>
A text content block element is a <a>text content element</a>
that serves as a standalone element for a unit of text, and
which may optionally contain certain child <a>text content
elements</a> (e.g.
<a href="text.html#TextElement"><span class="element-name">'tspan'</span></a>).
<!--SVG Tiny 1.2 defines two text content block elements:
<a href="text.html#TextElement"><span class="element-name">'text'</span></a>
and
<a href="text.html#TextAreaElement"><span class="element-name">'textArea'</span></a>-->
SVG 2 defines a single text content block element: <a>'text'</a>.
</dd>
<dt id="TermContentArea">content area</dt>
<dd>
The area in which the text is normally laid out. This is
equivalent to the
<a href="https://www.w3.org/TR/css3-exclusions/#content-area">CSS
content area</a>. The actual region where text layout occurs may
be smaller due to padding and/or exclusions.
<!-- CSS 2 reference: href="https://www.w3.org/TR/CSS2/box.html#box-dimensions" -->
</dd>
<dt id="TermWrappingContext">wrapping context</dt>
<dd>
One or more regions (shapes) to be excluded from the content
area during text layout. This is the same as the
<a href="https://www.w3.org/TR/css3-exclusions/#wrapping-context">
CSS wrapping context</a>.
</dd>
<dt id="TermWrappingArea">wrapping area</dt>
<dd>
The area in which the text is laid out after subtracting any
padding or exclude areas (<a>wrapping context</a>). This is the
same as the
<a href="https://www.w3.org/TR/css3-exclusions/#wrapping-area">
CSS wrapping area</a>.
</dd>
<dt id="TermLineBox">line box</dt>
<dd>
The rectangular area containing all the content used to layout a single line of text.
This is the same as the
<a href="https://www.w3.org/TR/CSS2/visuren.html#line-box">CSS line box</a>.
<p class="annotation">
Although various CSS 3 text layout specs use the term,
none current establish a formal definition.
The link is therefore to CSS 2.1,
and <a href="https://github.com/w3c/csswg-drafts/issues/363">an issue has been filed with CSS WG</a>.
</p>
</dd>
<!-- The following two terms are taken from CSS Writing Modes 3, simplified for SVG.-->
<dt id="TermInlineBaseDirection">inline-base direction</dt>
<dd>
The primary direction in which content is ordered within a line
or part of a line of text. It defines the <q>start</q> and
<q>end</q> sides of a line or part of a line of text (relevant,
for example to how the <a>'text-anchor'</a> property is
applied). It is determined by the <a>'direction'</a> property.
(Note: the ordering of characters in a line of text is primary
controlled by the Unicode bidi algorithm and not the inline-base
direction.)
</dd>
<dt id="TermBlockFlowDirection">block-flow direction</dt>
<dd>
The direction in which <a>line boxes</a> are stacked. It is
determined by the <a>'writing-mode'</a> property.
</dd>
<dt id="TermAlignmentPoint">alignment point</dt>
<dd>
The point on a typographic character that should be aligned with
the <a>current text position</a>. It is determined by the glyph
cell metrics and may depend on the script and
<a>inline-base direction</a>.
</dd>
<dt id="TermCurrentTextPosition">current text position</dt>
<dd>
The point in the current user space where the <a>alignment
point</a> of the next typographic character to be rendered
should be placed.
</dd>
<dt id="TermTextChunk">text chunk</dt>
<dd>
An independent block of text in which all characters are
positioned together. Each new absolute positioning adjustment
(due to an <a>'tspan/x'</a> or <a>'tspan/y'</a> attribute, or
forced line break) creates a new <a>text chunk</a>. Ligature
substitution and bidi-reordering only occur within a <a>text
chunk</a>. <a>Text chunks</a> are only relevant to pre-formatted
text.
</dd>
<dt id="TermWhiteSpaceCharacter">white space characters</dt>
<dd>The following characters are considered white space characters:
U+0009 CHARACTER TABULATION,
U+000C FORM FEED (FF),
U+000D CARRIAGE RETURN (CR),
U+000A LINE FEED (LF) and
U+0020 SPACE.
</dd>
</dl>
<h3 id="FontsGlyphs">Fonts and glyphs</h3>
<p>
A font consists of a collection of glyphs together with other
information (collectively, the font tables) necessary to use those
glyphs to present characters on some visual medium. The
combination of the collection of glyphs and the font tables is
called the <em>font data</em>.
</p>
<p>
A font may supply substitution and positioning tables that
can be used by a formatter (text shaper) to re-order, combine and
position a sequence of glyphs to form one or more composite
glyphs. The combining 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. The tables may
be language dependent, allowing the use of language appropriate
letter forms.
</p>
<p>
When a glyph, simple or composite, represents an indivisible unit
for typesetting purposes, it is know as a <a>typographic
character</a>.
</p>
<p>
Ligatures are an important feature of advance text layout. Some
ligatures are discretionary while others (e.g. in Arabic) are
required. The following explicit rules apply to ligature
formation:
</p>
<ul>
<li>
<p>
Ligature formation should not be enabled when characters are
in different DOM text nodes;
thus, characters separated by markup should not use ligatures.
</p>
</li>
<li>
<p>
Ligature formation should not be enabled when characters are
in different <a>text chunks</a>.
</p>
</li>
<li>
<p>
Discretionary ligatures should not be used when the spacing
between two characters is not the same as the
default space (e.g. when <a>'letter-spacing'</a> has a
non-default value, or <a>'text-align'</a> has a value of
<span class="propvalue">justify</span>
and <a>'text-justify'</a> has a value of <span class="propvalue">distribute</span>).
(See
<a href="https://www.w3.org/TR/css-text-3/#letter-spacing-property">CSS
Text Module Level 3</a>,
([<a href="refs.html#ref-css-text-3">css-text-3</a>]).
</p>
<p>
SVG attributes such as <a>'tspan/dx'</a>, <a>'textLength'</a>,
and <a>'textPath/spacing'</a> (in <a>'textPath'</a>) that may
reposition <a>typographic characters</a> do not break discretionary
ligatures.
If discretionary ligatures are not desired they can be turned
off by using the <a>'font-variant-ligatures'</a> property.
</p>
<p>
For OpenType fonts, discretionary ligatures include those enabled
by the liga, clig, dlig, hlig, and cala features; required ligatures
are found in the rlig feature.
</p>
</li>
</ul>
<div class="annotation svg2-requirement">
<table>
<tr>
<th>SVG 2 Requirement:</th>
<td>Include explicit support for Web Open Font Format (WOFF).</td>
</tr>
<tr>
<th>Resolution:</th>
<td><a href="http://www.w3.org/2011/03/01-svg-minutes.html#item03">We will mandate WOFF support in SVG 2.</a></td>
</tr>
<tr>
<th>Purpose:</th>
<td>To allow access to full OpenType features for internationalization and advanced typography.</td>
</tr>
<tr>
<th>Owner:</th>
<td>Chris (no action)</td>
</tr>
<tr>
<th>Status:</th>
<td>Done</td>
</tr>
</table>
</div>
<p>
Proper text rendering may depend on using the same font as used
during authoring. For this reason SVG requires support for
downloadable fonts as defined in the
<a href="https://www.w3.org/TR/css-fonts-3/#font-resources">Font
Resources</a> section of the
<a href="https://www.w3.org/TR/css-fonts-3/">CSS Fonts
Module</a>. In particular, support for the Web Open Font Format
[<a href="refs.html#ref-woff">WOFF</a>] is required.
</p>
<p class="note">
New in SVG 2, WOFF allows authors to provide the fonts needed to
properly render their content. This includes ensuring that the
fonts have the proper OpenType tables to support complex scripts,
discretionary ligatures, swashes, old-style numbers, and so
on. WOFF also allows the fonts to be compressed, subsetted, and
include licensing information.
</p>
<h3 id="GlyphsMetrics">Glyph metrics and layout</h3>
<p>
Glyph selection and positioning is normally handled according to
the rules of CSS. In some cases, however, the final layout of text
in SVG requires knowledge of the geometry properties of individual
glyphs.
</p>
<p>
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.) The box 1 EM high and 1 EM
wide is called the <em>design space</em>. This space is given a
geometric coordinates by sub-dividing the EM into a number
of <em>units per em</em>.
</p>
<p class="note">
Units per em is a font characteristic. A typical value
for units per em is 1000 or 2048.
</p>
<p>
The coordinate space of the EM box is called the <em>design space
coordinate system</em>. For scalable fonts, the curves and lines
that are used to draw a glyph are represented using this
coordinate system.
</p>
<p class="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. The descenders on lowercase roman
letters have negative coordinate values.
</p>
<div class="figure">
<img class="bordered" src="images/text/font_embox.svg"
alt="An 'M' inside an EM box showing the coordinate system, baseline,
ascent and descent."/>
<p class="caption">
An 'M' inside an Em box (blue square). The 'M' sits on the
baseline (blue line). The origin of the coordinate system is
shown by the small black circle.
</p>
</div>
<p>
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.
</p>
<p class="note">
Within an OpenType font ([<a href="refs.html#ref-opentype">OPENTYPE</a>]),
for horizontal writing-modes,
the ascent and descent are given by the sTypoAscender and
sTypoDescender 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.
</p>
<p>
Glyphs are positioned relative to a particular point on each glyph
known as the <a>alignment point</a>. For horizontal
writing-modes, the glyphs' <a>alignment points</a> are vertically
aligned while for vertical writing-modes, they are horizontally
aligned. The position of the <a>alignment point</a> depends on the
script. For example, Western glyphs are aligned at the bottom of
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.
</p>
<p>
Within a script and within a line of text having a single
font-size, the sequence of alignment points defines, in the
<a>inline-base direction</a>, a geometric line called a
<dfn id="TermBaseline" data-dfn-type="dfn" data-export="">baseline</dfn>. 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.
</p>
<div class="figure">
<img class="bordered" src="images/text/font_baseline.svg"
alt="Baseline example in three different scripts."/>
<p class="caption">
Example baselines (red lines) in three different scripts. From
left to right: alphabetic, hanging, ideographic. The EM box is
shown in blue for the ideographic script.
</p>
</div>
<p>
As glyphs are sequentially placed along a baseline, the
<a>alignment point</a> of a glyph is typically positioned at the
<a>current text position</a> (some properties such as
<a>'vertical-align'</a> may alter the positioning). After each
glyph is placed, the <a>current text position</a> is advanced by
the glyph's <em>advance</em> value (typically the width for
horizontal text or height for vertical text) with any correction
for kerning or other spacing adjustment as well as for new lines
in pre-formatted or auto-wrapped text. The initial and final
current text positions are used for alignment (e.g. when
the <a>'text-anchor'</a> value is either 'middle' or 'end'). The
glyph's advance is needed when placing text along a path.
</p>
<div class="figure">
<img class="bordered" src="images/text/font_metrics.svg"
alt="Baseline example in three different scripts."/>
<p class="caption">
Example of font metrics. The blue boxes show the geometric
boxes for the three glyphs. The labeled small circles show the
<a>current text position</a> before glyph placement. The
small square shows the final <a>current text position</a>
after placing the last glyph. Note that the left side of
the 'a' glyph's box is not aligned with the right side of
the 'V' glyph's box due to kerning.
</p>
</div>
<p>
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 <em>em</em> size.
</p>
<p>
The initial <a>current text position</a> is established by the
<a>'text/x'</a> and <a>'text/y'</a> attributes on the
<a>'text'</a> element or first rendered <a>'tspan'</a> element for
pre-formatted text, or auto-wrapped text when the <a>content
area</a> is determined by the <a>'inline-size'</a> property. For
other auto-wrapped text, the initial <a>current text position</a>
is determined by the position of the first rendered glyph after
applying the CSS line wrapping algorithm.
</p>
<p>
A <dfn id="TermBaselineTable" data-dfn-type="dfn" data-export="">baseline-table</dfn> 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.
</p>
<p class="note">
Some fonts may not have values for the baseline tables. Heuristics
are suggested for approximating the baseline tables in
<a href="https://www.w3.org/TR/css-inline-3/#baseline-synthesis-fonts">CSS
Inline Layout Module Level 3</a> [css-inline-3]
when a given font does not supply baseline tables.
</p>
<p>
When a different font (or change in font size) is specified in the
middle of a run of text, the <dfn id="TermDominantBaseline" data-dfn-type="dfn" data-export="">dominant baseline</dfn>
determines the baseline used to align glyphs in the new font (new
size) to those in the previous font. The
<a>'dominant-baseline'</a> property is used to set the dominant
baseline.
</p>
<p>
Alignment between an object relative to its parent is determined
by the <dfn id="TermAlignmentBaseline" data-dfn-type="dfn" data-export="">alignment baseline</dfn>. It is normally the same
baseline as the dominant baseline but by using the shorthand
<a>'vertical-align'</a> property (preferred) or the longhand
<a>'alignment-baseline'</a> another baseline can be chosen.
</p>
<p>
The dominant baseline can be temporarily shifted (as needed
for superscripts or subscripts) by using either the shorthand
<a>'vertical-align'</a> property (preferred) or the longhand
<a>'baseline-shift'</a> property. Note that shifts can be
nested, each shift added to the previous shift.
</p>
<div class="figure">
<img class="bordered" src="images/text/vertical_align.svg"
alt="Examples of using the 'vertical-align' property. Left shows '[[z]]' where the inner brackets are smaller. Right shows 'x2' where the '2' is a superscript."/>
<p class="caption">
Examples of using the 'vertical-align' property.
Left: 'vertical-align:mathematical'
('alignment-baseline:mathematical') is applied to
the <a>'tspan'</a> containing '[z]'. The light-blue line shows
the position of the mathematical baseline.
Right: 'vertical-align:super' ('baseline-shift:super') applied
to the <a>'tspan'</a> containing '2'. The light-blue lines
indicate the shift in baseline.
</p>
</div>
<p>
SVG further assumes that for each glyph in the font data for a
font, there 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 <a>inline-base direction</a>
position of the alignment point is on the start-edge of the glyph.
</p>
<p>
Additional information on baselines can be found in the
<a href="https://www.w3.org/TR/css-inline-3/#line-height">CSS
Inline Layout Module Level 3</a> specification.
[<a href="refs.html#ref-css-inline-3">css-inline-3</a>]
(Also see: <a href="https://www.w3.org/TR/css3-writing-modes/#intro-baselines">CSS
Writing Modes Level 3</a> specification.
[<a href="refs.html#ref-css-writing-modes-3">css-writing-modes-3</a>])
</p>
<div class="annotation svg2-requirement">
<table>
<tr>
<th>SVG 2 Requirement:</th>
<td>Support text aligned to different baselines.</td>
</tr>
<tr>
<th>Resolution:</th>
<td><a href="http://www.w3.org/2012/03/15-svg-irc#T21-07-21">SVG 2 will support glyphs being aligned to different baselines, perhaps by using existing or improved CSS properties.</a></td>
</tr>
<tr>
<th>Purpose:</th>
<td>To allow glyphs in horizontal text to have different vertical alignments for stylistic effects.</td>
</tr>
<tr>
<th>Owner:</th>
<td>Chris (no action)</td>
</tr>
<tr>
<th>Status:</th>
<td>Done</td>
</tr>
</table>
</div>
<p>
A single line of text is laid out inside a <a>line box</a>.
Multi-line text is produced by stacking these boxes. The height of
a <a>line box</a> is determined by finding the maximum ascent and
the maximum descent of all the glyphs in a line of text after
applying the effect of the <a>'line-height'</a> property. The
width of a <a>line box</a> is normally the width of the containing
text block. In SVG, when the containing text block does not have a
fixed geometry (as with pre-formatted text), the <a>line box</a>
tightly wraps the glyph boxes within the box.
</p>
<div class="figure">
<img class="bordered" src="images/text/line_box.svg"
alt="The sentence 'A big word.' where 'big' is in a larger font."/>
<p class="caption">
Example of determining the height of a <a>line box</a>.
First each glyph box (small light-blue boxes) is extended
vertically above and below according to the <a>'line-height'</a>
property. In this case the <a>'line-height'</a> property is
125%. The larger glyphs have a <a>'font-size'</a> of 96px so
their extra height is 24px (25% of 96px). The extra height is
evenly divided above and below resulting in the red boxes. (For
clarity, all glyphs in the same inline element have been grouped
together).
The final <a>line box</a> (large light-blue box) is then found
using the maximum extents of the red boxes above and below the
baseline.
</p>
</div>
<p>
In order to support various international writing systems, <a>line
boxes</a> may be orientated in a horizontal or vertical direction.
Text within a vertical <a>line box</a> flows from top to bottom.
Text within a horizontal <a>line box</a> may flow left-to-right
(e.g., modern Latin scripts), right-to-left (e.g., Hebrew or
Arabic), or a mixture of left-to-right and right-to-left
(bidirectional text).
</p>
<p>
The processing model for bidirectional text is as follows:
</p>
<ul>
<li>
The
user agent processes the characters which are provided in
<em>logical order</em> (i.e., the order the characters appear in
the original document).
</li>
<li>
The user agent excludes non-rendered elements
and <a href="#WhiteSpace">collapses white space</a>.
</li>
<li>
The user agent determines
the set of independent blocks within each of which it should apply
the Unicode bidirectional algorithm.
<ul>
<li>
Each <a>text chunk</a> represents an independent block of text.
</li>
<li>
Any change in glyph
orientation due to processing of the
<a>'text-orientation'</a> or obsoleted
<a>'glyph-orientation-vertical'</a> properties
will start a new independent
blocks of text for bi-directional purposes.
</li>
</ul>
</li>
<li>
After processing the Unicode bidirectional
algorithm and properties <a>'direction'</a> and
<a>'unicode-bidi'</a> on each of the independent text blocks, the
user agent will have a potentially re-ordered list of characters
which are now in left-to-right rendering order. Simultaneous with
re-ordering of the characters, the <a>'tspan/dx'</a>,
<a>'tspan/dy'</a>, and <a>'tspan/rotate'</a> attributes on the
<a>'text'</a> and <a>'tspan'</a> elements are also re-ordered to
maintain the original correspondence between characters and
attribute values.
</li>
</ul>
<p>
While kerning or ligature processing might be
font-specific, the preferred model is that kerning and ligature
processing occurs between combinations of characters or glyphs
after the characters have been re-ordered.
</p>
<p>
The orientation of <a>line boxes</a> as well as the direction in
which they are stacked (<a>block-flow direction</a>) is determined
by the <a>'writing-mode'</a> property. For horizontal text
(<a>'writing-mode'</a> value
<span class="prop-value">horizontal-tb</span>) <a>line boxes</a>
are stacked from top to bottom. For vertical text, <a>line boxes</a>
are stacked from right-to-left (<a>'writing-mode'</a> value
<span class="prop-value">vertical-rl</span>) or left-to-right
(<a>'writing-mode'</a> value
<span class="prop-value">vertical-lr</span>).
</p>
<h2 id="TextElement">The <span class="element-name">'text'</span> and
<span class="element-name">'tspan'</span> elements</h2>
<p>
The <a>'text'</a> element defines a graphics element consisting of
text. The <a>'tspan'</a> element within a <a>'text'</a> or another
<a>'tspan'</a> element, allows one to switch the style and/or
adjust the position of the rendered text inside the <a>'tspan'</a>
element relative to the parent element.
</p>
<p>
The character data within the <a>'text'</a> and <a>'tspan'</a>
elements, along with relevant attributes and properties, and
character-to-glyph mapping tables within the font itself, define
the glyphs to be rendered. The attributes and properties on
the <a>'text'</a> and <a>'tspan'</a> elements 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.
</p>
<p>
Since <a>'text'</a> and <a>'tspan'</a> elements are rendered using
the same rendering methods as other graphics elements, all of the
same
<a href="painting.html">painting</a> features that apply to
<a>shapes</a> such as <a href="paths.html">paths</a> and
<a href="shapes.html#RectElement">rectangles</a> also apply to
<a>'text'</a> and <a>'tspan'</a> elements,
except for <a>markers</a>.
In addition,
<a href="coords.html">coordinate system transformations</a>,
<a href="render.html#ClippingAndMasking">clipping</a>, and
<a href="render.html#ClippingAndMasking">masking</a> can be applied
to the <a>'text'</a> element as a whole.
</p>
<p class="note">
In CSS terms, the <a>'text'</a> element acts as a block
element. The <a>'tspan'</a>, <a>'textPath'</a>, and <a>'a'</a>
elements that are descended from <a>text content elements</a> act as
inline elements.
</p>
<p id="ObjectBoundingBoxUnitsTextObjects">
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 <span class="attr-value">'objectBoundingBox'</span> is
used (see
<a href="coords.html#ObjectBoundingBox">Object bounding box
units</a>) to specify a graphical effect relative to the "object
bounding box", then the object bounding box units are computed
relative to the entire <a>'text'</a> element in all cases, even
when different effects are applied to different <a>'tspan'</a> or <a>'textPath'</a>
elements within the same <a>'text'</a> element.
</p>
<p>
The <a>'text'</a> element renders its first glyph (after
bidirectionality
reordering) at the initial <a>current text position</a> (with
possible adjustments due to the value of the
<a>'text-anchor'</a> property or the <a>'text-align'</a> property).
For pre-formatted text and for auto-wrapped text where the
<a>content area</a> is determined by the <a>'inline-size'</a>
property, the initial <a>current text
position</a> is determined by the <a>'tspan/x'</a> and
<a>'tspan/y'</a> values of the <a>'text'</a> or <a>'tspan'</a>
element which contains the first rendered character.
For auto-wrapped text in a shape or text on a path see
the <a href="text.html#TextLayoutAuto">Auto-wrapped text</a> or
<a href="text.html#TextLayoutPath">Text on a path</a> sections,
respectively, to determine the initial <a>current text
position</a>.
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
<a href="text.html#TextLayoutAlgorithm">text layout</a> for a description
of glyph placement and glyph advance.
</p>
<div class="example">
<p>
The text string <q>Hello, out there!</q> is rendered onto the
canvas using the Verdana font family with the glyphs filled
with the color blue.
</p>
<edit:includefile href='images/text/text01.svg' image='yes' link='yes'/>
<div class="figure">
<img class="bordered" src="images/text/text01.svg"
alt="Image showing the blue text."/>
</div>
</div>
<div class="example">
<p>
A <a>'tspan'</a> is used to change the styling of the word <q>not</q>.
</p>
<edit:includefile href='images/text/tspan01.svg' image='yes' link='yes'/>
<div class="figure">
<img class="bordered" src="images/text/tspan01.svg"
alt="Blue text except the word 'not' is red."/>
</div>
</div>
<div class="example">
<p>
Two <a>'tspan'</a> elements are repositioned horizontally and
vertically using the <a>'text/x'</a> and <a>'text/y'</a>
attributes. Because all the text is within a single
<a>'text'</a> element, a user will be able to select through all
the text and copy it to the system clipboard in user agents that
support <a href="text.html#TextSelection">text selection and
clipboard operations</a>.
</p>
<edit:includefile href='images/text/tspan02.svg' image='yes' link='yes'/>
<div class="figure">
<img class="bordered" src="images/text/tspan02.svg"
alt="A sentence with several shifted words."/>
</div>
</div>
<edit:with element='text'>
<edit:elementsummary name='text'/>
<div class="annotation svg2-requirement">
<table>
<tr>
<th>SVG 2 Requirement:</th>
<td>Allow transforms on <a>'tspan'</a>.</td>
</tr>
<tr>
<th>Resolution:</th>
<td><a href="http://www.w3.org/2011/12/01-svg-irc#T21-02-34">SVG 2 will allow transforms on <span class="element-name">'tspan'</span>.</a></td>
</tr>
<tr>
<th>Purpose:</th>
<td>Align with other elements such as <a>'a'</a> which already allow transforms.</td>
</tr>
<tr>
<th>Owner:</th>
<td>Cameron (no action)</td>
</tr>
<tr>
<th>Status:</th>
<td>Done</td>
</tr>
</table>
<p>
This decision was reversed. See
<a href="https://github.com/w3c/svgwg/issues/210">GitHub Issue
210</a>. CSS/HTML does not allow transforms on inline elements
and no renderer supports transforms on the <a>'a'</a> element
when inline (in both SVG and HTML).
</p>
</div>
<edit:elementsummary name='tspan'/>