[css-fonts-4] Refactor @font-feature-values grammar, improve autolinking, add more examples #9311

Author: svgeesus

css-fonts-4/Overview.bs

@@ -5629,20 +5629,29 @@ and be sure they're not accidentally turning on unrelated features
 
 An ''@font-feature-values'' rule's prelude
 contains a list of font family names,
-followed by a block containing multiple <<feature-value-block>>s,
+followed by a block containing multiple ''feature-value-block''s,
 a special type of subsidiary at-rule.
-Each <<feature-value-block>> contains declarations
+Each ''feature-value-block''' contains declarations
 mapping author-chosen human-friendly names
 (such as "flowing")
 to feature indexes for the associated feature.
 
-<pre class=prod>
-@font-feature-values <<family-name>># { <<declaration-rule-list>> }
+Each <<font-feature-value>> has the same meaning 
+as the corresponding value of the 'font-variant-alternates' property.
 
-<<feature-value-block>> = <<font-feature-value-type>> { <<declaration-list>> }
+<pre class=prod export>
+@font-feature-values = <<family-name>># { <<declaration-rule-list>> }
 
-<<font-feature-value-type>> = @stylistic | @historical-forms | @styleset | @character-variant
-	| @swash | @ornaments | @annotation
+<dfn for="@font-feature-values">font-feature-value-type</dfn> = <<@stylistic>> | <<@historical-forms>> | <<@styleset>> | <<@character-variant>>
+	| <<@swash>> | <<@ornaments>> | <<@annotation>> 
+
+<dfn for="@font-feature-values">@stylistic</dfn> = @stylistic { <<declaration-list>> }
+<dfn for="@font-feature-values">@historical-forms</dfn> = @historical-forms { <<declaration-list>> }
+<dfn for="@font-feature-values">@styleset</dfn> = @styleset { <<declaration-list>> }
+<dfn for="@font-feature-values">@character-variant</dfn> = @character-variant { <<declaration-list>> }
+<dfn for="@font-feature-values">@swash</dfn> = @swash { <<declaration-list>> }
+<dfn for="@font-feature-values">@ornaments</dfn> = @ornaments { <<declaration-list>> }
+<dfn for="@font-feature-values">@annotation</dfn> = @annotation { <<declaration-list>> }
 </pre>
 
 <wpt>
@@ -5664,9 +5673,11 @@ and must be ignored.
 The ''@font-feature-values'' block accepts <<declaration-rule-list>> as its contents;
 these list items are either:
 
-[=at-rules=] named by one of the <<font-feature-value-type>> at-keyword tokens,
+- [=at-rules=] named by one of the <<font-feature-value-type>> at-keyword tokens
+
 or
-the '@font-feature-values/font-display' descriptor.
+
+- the '@font-feature-values/font-display' descriptor.
 
 <!-- TODO: tab says "The OM needs to make sure it exposes both .style and .childRules or whatever." -->
 
@@ -5803,11 +5814,29 @@ specific additions made per-page.
 Multi-valued feature value definitions</h4>
 
 	Most <em>font specific</em> functional values of the 'font-variant-alternates' property
-	take a single value (e.g. ''swash()'').
-	The ''character-variant()'' property value allows two values
-	and ''styleset()'' allows an unlimited number.
+	take a single value (e.g. ''swash()'') which enables the feature.
+
+<pre class="example" id="ex-single-valued-feature" highlight=css>@font-feature-values Jupiter Serif {
+
+	@swash {
+		swishy: 5;     /* implies ss05 = 1 */
+		swirly: 2;     /* implies ss02 = 1 */
+	}
+}
+</pre>
 
-	For the styleset property value, multiple values indicate the style
+	The ''character-variant()'' property value and the ''@character-variant'' descriptor allow two values,
+	which enables a feature (from ther first value) and sets it to a given (second) value.
+
+<pre class="example" id="ex-two-valued-feature" highlight=css>@font-feature-values MM Greek {
+	
+		@character-variant { alpha-2: 1 2; }   /* implies cv01 = 2 */
+		@character-variant { beta-3: 2 3; }    /* implies cv02 = 3 */
+	}
+</pre>
+
+	For the ''styleset()'' property value and ''@styleset'' rule,
+	multiple values indicate the style
 	sets to be enabled.  Values between 1 and 99 enable OpenType features
 	<span class="tag">ss01</span> through <span class="tag">ss99</span>.
 	However, the OpenType standard only officially defines
@@ -5816,7 +5845,8 @@ Multi-valued feature value definitions</h4>
 	generate a syntax error when parsed but enable no OpenType features.
 
 
-<pre class="example" id="ex-multi-valued-feature">@font-feature-values Mars Serif {
+<pre class="example" id="ex-multi-valued-feature" highlight=css>@font-feature-values Mars Serif {
+
 	@styleset {
 	alt-g: 1;        /* implies ss01 = 1 */
 	curly-quotes: 3; /* implies ss03 = 1 */
@@ -5837,7 +5867,7 @@ p.codeblock {
 	font-variant-alternates: styleset(curly-quotes, code);
 }</pre>
 
-	For character-variant, a single value between 1 and 99 indicates
+	For <<@character-variant>>, a single value between 1 and 99 indicates
 	the enabling of OpenType feature <span class="tag">cv01</span> through
 	<span class="tag">cv99</span>. For OpenType fonts, values greater than
 	99 or equal to 0 are ignored but do not generate a syntax error when parsed
@@ -5848,7 +5878,8 @@ p.codeblock {
 	feature value definition</i> is
 	ignored.
 
-<pre class="example" id="ex-greek-variant-features">@font-feature-values MM Greek {
+<pre class="example" id="ex-greek-variant-features" highlight=css>@font-feature-values MM Greek {
+
 	@character-variant { alpha-2: 1 2; }   /* implies cv01 = 2 */
 	@character-variant { beta-3: 2 3; }    /* implies cv02 = 3 */
 	@character-variant { epsilon: 5 3 6; } /* more than 2 values, syntax error, definition ignored */
@@ -5883,7 +5914,8 @@ p {
 	a font without variants.  Note the two variants for U and N used on the
 	seal.</p>
 
-<pre>@font-feature-values Athena Ruby {
+<pre highlight=css>@font-feature-values Athena Ruby {
+
 	@character-variant {
 	leo-B: 2 1;
 	leo-M: 13 3;
@@ -5897,7 +5929,7 @@ p {
 
 p {
 	font-variant: discretionary-ligatures
-				character-variant(leo-B, leo-M, leo-N, leo-T, leo-U);
+	character-variant(leo-B, leo-M, leo-N, leo-T, leo-U);
 }
 
 span.alt-N {