after review round 1

Author: davidsgrogan

css-fonts-5/Overview.bs

@@ -25,6 +25,7 @@ spec:css-color-4; type:property; text:color
 spec:css-values; type:value; text:ex
 spec:css22; type:value; for:/; text:block
 spec:html; type:element; text:font
+spec:html; type:element; text:meta
 spec:css-fonts-4; type:property; text:font-size
 spec:css-fonts-4; type:descriptor; text:font-language-override
 spec:css-fonts-4;  type:property; text:font-family
@@ -62,12 +63,17 @@ Do not assume that if something is not here, it has been dropped.
 <h2 id="text-scale-meta">
 Text-Scale <code class=html>&lt;meta&gt;</code> element</h2>
 
-A document with a <code>&lt;meta></code> tag whose <code>name</code> attribute
+A document with a <{meta}> tag
+whose <code>name</code> attribute
 is a <a>ASCII case-insensitive</a> match for
-<dfn lt=text-scale><code>"text-scale"</code></dfn> is recognized as setting the
-initial font size of the document. The value of the <code>content</code>
+<dfn lt=text-scale><code>"text-scale"</code></dfn>
+is recognized as setting the computed value
+of the ''font-size/medium'' font size
+and consequently scaling the computed size of the other <<absolute-size>> keywords.
+
+The value of the <code>content</code>
 attribute must be an <a>ASCII case-insensitive</a> match for one of the
-recognized keywords.
+recognized keywords. Otherwise the tag is ignored.
 
 Documents without this <code>&lt;meta></code> tag will have an assumed default
 value of <code>legacy</code>.
@@ -76,21 +82,29 @@ value of <code>legacy</code>.
 Keywords</h3>
 
 The recognized keywords in the [=text-scale=]
-<code class=html>&lt;meta&gt;</code> element are:
-
-<ul>
-	<li><code class="index" lt="legacy!!text-scale-meta">legacy</code></li>
-	<li><code class="index" lt="scale!!text-scale-meta">scale</code></li>
-</ul>
+<{meta}> element are:
+
+<dl>
+	<dt><dfn for="text-scale"><code>legacy</code></dfn></dt>
+	<dd>''env()/preferred-text-scale'' returns the user's OS-level font factor on mobile,
+	but 1 on desktop.
+	The document's initial font size only incorporates UA-level font preferences.
+	OS-level font preferences are ignored.</dd>
+	<dt><dfn>scale</dfn></dt>
+	<dd>''env()/preferred-text-scale'' returns the user's OS-level font preferences.
+	The document's initial font size incorporates both UA-level and OS-level font preferences.</dd>
+</dl>
 
 <h3 id="legacy-keyword">The 'legacy' keyword</h3>
 
-The <dfn for="text-scale" export><code>legacy</code></dfn> property is
-recognized in the [=text-scale=] content attribute value.
-
 When the value of the [=text-scale=] content attribute is
-<a for="text-scale">legacy</a> the user agent should set the initial font size
-to 16px multiplied by the font scale factor the user has chosen from any settings <i>provided by the user agent</i>. The ''preferred-text-scale'' value must be 1 on desktop platforms. On mobile:
+[=text-scale/legacy=]
+the user agent must set the computed ''font-size/medium'' font size
+to 16px multiplied by
+the font scale factor
+the user has chosen from any settings <i>provided by the user agent</i>.
+The ''preferred-text-scale'' value must be 1 on desktop platforms.
+On mobile:
 <ul>
 	<li>if the operating system provides a text scale setting AND the UA hasn't already applied that factor to the initial font size, ''env()/preferred-text-scale'' returns the mulitplier that the user has chosen in the operating system's text scale setting.
 
@@ -106,10 +120,12 @@ The <dfn for="text-scale" export><code>scale</code></dfn> property is
 recognized in the [=text-scale=] content attribute value.
 
 When the value of the [=text-scale=] content attribute is
-<a for=text-scale>scale</a> the user agent may determine the initial font size
-based on a combination of the operating system's text scale setting and the user agent's text scale setting. The
-''env()/preferred-text-scale'' value must be a number that, when multiplied by
-16px, provides a <<length>> that matches that of the initial font size.
+<a for=text-scale>scale</a>
+computed ''font-size/medium'' font size must match the user's preferred paragraph text size as determined from a combination of OS and UA preferences.
+
+The ''env()/preferred-text-scale'' value must be a number that,
+when multiplied by 16px,
+provides a <<length>> that matches that of the initial font size.
 
 Further, when the value of the [=text-scale=] content attribute is
 <a for=text-scale>scale</a>, the user agent should skip all font-sizing interventions it would otherwise perform in an attempt to automatically honor the user's preferences. E.g. text autosizing on mobile (See [[css-size-adjust#intro]]) and full-application zoom (<a href="https://github.com/w3c/csswg-drafts/blob/main/css-env-1/explainers/env-preferred-text-scale.md#windows-11">popular browsers do this on Windows)</a>.