Merge pull request w3c#6382 from fantasai/font-size-adjust

[css-fonts-5] Extend font-size-adjust

Author: svgeesus

css-fonts-5/Overview.bs

@@ -93,13 +93,235 @@ Issue(4044):
 <h3 id="font-size-adjust-prop">
 Relative sizing: the 'font-size-adjust' property</h3>
 
-The 'font-size-adjust' property is applied after the 'size-adjust' descriptor.
+	<pre class="propdef">
+	Name: font-size-adjust
+	Value: none | [ ex | cap | ch | ic ]? [ from-font | <<number>> ]
+	Initial: none
+	Applies to: all elements and text
+	Inherited: yes
+	Percentages: N/A
+	Computed value: the keyword ''font-size-adjust/none'', or a pair of a metric keyword and a <<number>>
+	Animation type: discrete if the keywords differ, otherwise by computed value type
+	</pre>
+
+	For any given font size, the apparent size and effective legibility of text
+	varies across fonts as a function of their design.
+	For example,
+	for bicameral scripts such as Latin or Cyrillic that
+	distinguish between upper and lowercase letters,
+	the relative height of lowercase letters
+	compared to their uppercase counterparts
+	is a determining factor of legibility.
+	In situations where font fallback occurs,
+	fallback fonts might not share
+	the same ratios as the desired font family
+	for key typographic metrics,
+	and will thus appear to be a different size
+	and possibly be less readable.
+
+	The 'font-size-adjust' property provides a way
+	to preserve the readability and apparent size of text
+	when font fallback occurs.
+	It does this by adjusting the used font size
+	so that the specified metric is the same
+	regardless of the font used.
+
+	Values have the following meanings:
+
+	<dl dfn-type=value dfn-for="font-size-adjust">
+		<dt><dfn>none</dfn>
+		<dd>
+			No special 'font-size' adjustment is applied.
+
+		<dt><dfn>ex | cap | ch | ic</dfn>
+		<dd>
+			Specifies the font metric to normalize,
+			defaulting to ''font-size-adjust/ex'':
+
+			<dl>
+				<dt><dfn>ex</dfn>
+				<dd>
+					Normalize the <dfn dfn>aspect value</dfn> of the fonts,
+					using the x-height divided by the font size.
+
+				<dt><dfn>cap</dfn>
+				<dd>
+					Normalize the cap-height of the fonts,
+					using the cap-height by the font size.
+
+				<dt><dfn>ch</dfn>
+				<dd>
+					Normalize the narrow pitch of the fonts,
+					using the advance measure of “0” (ZERO, U+0030)
+					divided by the font size.
+
+				<dt><dfn>ic</dfn>
+				<dd>
+					Normalize the wide pitch of the font,
+					using the advance measure of “水” (CJK water ideograph, U+6C34)
+					divided by the font size.
+			</dl>
+
+			ISSUE(6384):
+			If the required font metric cannot be derived from a font,
+			then that font’s size is not adjusted.
+
+		<dt><dfn><<number>></dfn>
+		<dd>
+			Each font’s [=used value|used=] size is normalized
+			to match the chosen font metric to
+			this specified proportion of the [=computed value|computed=] 'font-size'.
+			In other words,
+			for each glyph,
+			the adjusted font size to use <var>u</var>
+			is calculated as:
+
+			<pre><var>u</var>  =  ( <var>m</var> / <var>m′</var> ) <var>s</var></pre>
 
-Note: The consequence of applying 'font-size-adjust' after 'size-adjust' is that
-'size-adjust' appears to have no effect.
+			where:
 
-Issue(5539):
+			<pre>
+			<var>s</var>  =  computed 'font-size' value
+			<var>m</var>  =  metric as specified by the 'font-size-adjust' property
+			<var>m′</var> =  metric as specified in the actual font
+			<var>u</var>  =  adjusted font-size to use
+			</pre>
+
+			Negative values are invalid.
+
+		<dt><dfn>from-font</dfn>
+		<dd>
+			Computes to the <<number>> corresponding to
+			the specified metric of the [=first available font=].
+
+			ISSUE(6384): Shouldn't this be the first available font
+			that can provide the required metric?
+	</dl>
 
+	<div class="example">
+		The style defined below defines Verdana as the desired font family,
+		but if Verdana is not available Futura or Times will be used.
+		One paragraph also has font-size-adjust specified.
+
+		<pre>
+			p {
+				font-family: Verdana, Futura, Times;
+			}
+			p.adj {
+				font-size-adjust: 0.545;
+			}
+
+			&lt;p>Lorem ipsum dolor sit amet, ...&lt;/p>
+			&lt;p class="adj">Lorem ipsum dolor sit amet, ...&lt;/p>
+		</pre>
+
+		Verdana has a relatively high aspect value of 0.545,
+		meaning lowercase letters are relatively tall
+		compared to uppercase letters,
+		so at small sizes text appears legible.
+		Times has a lower aspect value of 0.447,
+		and so if fallback occurs,
+		the text will be less legible at small sizes than Verdana
+		unless font-size-adjust is also specified.
+
+		Note: For text which uses diacritics,
+		too large an x-height will actually decrease legibility
+		as the diacritics become cramped.
+
+		How text rendered in each of these fonts compares is shown below,
+		the columns show text rendered in Verdana, Futura and Times.
+		The same font-size value is used across cells
+		within each row and red lines are included to show the differences in x-height.
+		In the upper half, each row is rendered in the same font-size value.
+		The same is true for the lower half,
+		but in this half the 'font-size-adjust' property is also set
+		to 0.545,
+		so that the actual font size is adjusted
+		to preserve the x-height of Verdana across each row.
+		Note how small text remains relatively legible across each row in the lower half.
+
+		<figure>
+			<img alt="text with and without 'font-size-adjust'" src="images/fontsizeadjust.png" >
+			<figcaption>Text with and without the use of 'font-size-adjust'</figcaption>
+		</figure>
+	</div>
+
+	The value of 'font-size-adjust' affects the [=used value|used=] value of 'font-size'
+	but does not affect the [=computed value|computed=] value.
+	Therefore it can affect the size of relative units
+	that are based on font metrics
+	such as <code>ex</code> and <code>ch</code>
+	but does not affect the size of <code>em</code> units.
+	Since numeric values of 'line-height'
+	refer to the [=computed value|computed=] size of 'font-size',
+	'font-size-adjust' also does not affect the [=used value|used=] value of 'line-height'.
+
+	Note: Since 'font-size-adjust' does not factor into the 'line-height',
+	specifying a line height too tightly can result in overlapping lines of text.
+	For example, when a fallback font with a low [=aspect value=]
+	is normalized to match one with a high [=aspect value=],
+	its ascenders and descenders are likely to extend outside the line box
+	with ''line-height: 1''.
+
+	The 'font-size-adjust' adjustment applies to any font that is selected
+	but in typical usage it would be based
+	on the corresponding metric value
+	of the first (most desired) font in the 'font-family' list.
+	If this is specified accurately,
+	the <code>(<var>m</var>/<var>m′</var>)</code> term in the adjustment formula
+	will resolve to <code>1</code> for the first font
+	and no adjustment occurs for that font;
+	and the rest of the fonts will resolve to match.
+	If the value is specified inaccurately,
+	text rendered using the first font in the family list
+	will display differently in older user agents
+	that don't support 'font-size-adjust'.
+
+	<div class="example">
+		Authors can calculate the <a>aspect value</a> for a given font
+		by comparing spans with the same content
+		but different 'font-size-adjust' properties.
+		If the same font-size is used, the spans will match
+		when the 'font-size-adjust' value is accurate for the given font.
+
+		Two spans with borders are used to determine the <a>aspect value</a> of a font.
+		The 'font-size' is the same for both spans
+		but the 'font-size-adjust' property is specified only for the right span.
+		Starting with a value of 0.5,
+		the aspect value can be adjusted
+		until the borders around the two letters line up.
+
+		<pre>
+		p {
+			font-family: Futura;
+			font-size: 500px;
+		}
+
+		span {
+			border: solid 1px red;
+		}
+
+		.adjust {
+			font-size-adjust: 0.5;
+		}
+
+		&lt;p>&lt;span>b&lt;/span>&lt;span class="adjust">b&lt;/span>&lt;/p>
+		</pre>
+
+		<figure>
+			<img alt="Futura with an aspect value of 0.5" src="images/beforefontsizeadjust.png" >
+			<figcaption>Futura with an <a>aspect value</a> of 0.5</figcaption>
+		</figure>
+
+		The box on the right is a bit bigger than the one on the left, so the <a>aspect value</a> of this font is something less than 0.5.
+		Adjust the value until the boxes align.
+	</div>
+
+	Note: If the specified metric has been overridden in ''@font-face'',
+	e.g. by 'size-adjust',
+	then the overridden metric will be used in the 'font-size-adjust' calculation.
+	Consequently, applying 'font-size-adjust' and 'size-adjust' together
+	means that 'size-adjust' appears to have no effect.
 
 <h2 id="font-resources">
 Font Resources</h2>
@@ -381,8 +603,15 @@ No new security or privacy considerations have been raised on this specification
 <h2 id="acknowledgments">
 Acknowledgments</h2>
 
-The CSS Working group would like to thank:
+	Firstly, the editors would like to thank all of the
+	<a href="https://www.w3.org/TR/css-fonts-4/#acknowledgments">contributors to the previous level of this module</a>.
 
+	Secondly, we would like to acknowledge
+	DerKoun from PDFReactor,
+	Xiaocheng Hu from Google,
+	and
+	Jonathan Kew from Mozilla,
+	for their contributions to the improvements in this Level 5.
 
 <h2 id="changes">
 Changes