[css-fonts-4] Move font-feature-values to Level 4

Author: svgeesus

css-fonts-4/Overview.bs

@@ -1949,11 +1949,11 @@ Font features and variations: the 'font-variant!!descriptor', 'font-feature-sett
 <pre class='descdef'>
 Name: font-variant
 Value: normal | none | [ <<common-lig-values>> || <<discretionary-lig-values>> || <<historical-lig-values>> ||
-        <<contextual-alt-values>> || <var title="stylistic">stylistic(<<feature-value-name>>)</var> || <var>historical-forms</var> ||
-        <var>styleset(<<feature-value-name>> #)</var> ||
-        <var>character-variant(<<feature-value-name>> #)</var> ||
-        <var>swash(<<feature-value-name>>)</var> || <var>ornaments(<<feature-value-name>>)</var> ||
-        <var>annotation(<<feature-value-name>>)</var> ||
+        <<contextual-alt-values>> || <var title="stylistic">stylistic(<&lt;feature-value-name&gt;>)</var> || <var>historical-forms</var> ||
+        <var>styleset(<&lt;feature-value-name&gt;> #)</var> ||
+        <var>character-variant(<&lt;feature-value-name&gt;> #)</var> ||
+        <var>swash(<&lt;feature-value-name&gt;>)</var> || <var>ornaments(<&lt;feature-value-name&gt;>)</var> ||
+        <var>annotation(<&lt;feature-value-name&gt;>)</var> ||
         [ <i>small-caps</i> | <i>all-small-caps</i> | <i>petite-caps</i> | <i>all-petite-caps</i> | <i>unicase</i> | <i>titling-caps</i> ] ||
         <<numeric-figure-values>> || <<numeric-spacing-values>> || <<numeric-fraction-values>> || <i>ordinal</i> || <i>slashed-zero</i> ||
         <<east-asian-variant-values>> || <<east-asian-width-values>> || <i>ruby</i> ||
@@ -2816,8 +2816,8 @@ and what they represent is font-specific, so these are each marked
 of these alternates is font-specific, the
 ''@font-feature-values'' rule is used to define values for a
 specific font family or set of families that associate a font-specific
-numeric <feature-index> with a custom
-<feature-value-name>, which is then used in this
+numeric &lt;feature-index&gt; with a custom
+&lt;feature-value-name&gt;, which is then used in this
 property to select specific alternates:
 
 <pre>@font-feature-values Noble Script { @swash { swishy: 1; flowing: 2; } }
@@ -2827,10 +2827,10 @@ p {
   font-variant-alternates: swash(flowing); /* use swash alternate #2 */
 }</pre>
 
-When a particular <feature-value-name> has not
+When a particular &lt;feature-value-name&gt; has not
 been defined for a given family or for a particular feature type, the
 computed value must be the same as if it had been defined.  However,
-property values that contain these undefined <feature-value-name>
+property values that contain these undefined &lt;feature-value-name&gt;
 identifiers must be ignored when choosing glyphs.
 
 <pre>/* these two style rules are effectively the same */
@@ -2896,7 +2896,330 @@ Individual values have the following meanings:
 <h3 id="font-feature-values">
 Defining font specific alternates: the ''@font-feature-values'' rule</h3>
 
-Issue: Moved to Level 4; port the text for this from Fonts 3 .src to Fonts 4 .bs
+Several of the possible values of 'font-variant-alternates' listed
+above are labeled as <em>font specific</em>.  For these features fonts may define
+not just a single glyph but a set of alternate glyphs with an index to
+select a given alternate.  Since these are font family specific, the
+''@font-feature-values'' rule is used to define named values for these indices
+for a given family.
+
+<div class="example">
+	<p>In the case of the swash Q in the example shown above, the swash could
+	be specified using these style rules:
+	</p>
+
+	<pre>
+
+	@font-feature-values Jupiter Sans {
+	  @swash {
+		delicate: 1;
+		flowing: 2;
+	  }
+	}
+
+	h2 { font-family: Jupiter Sans, sans-serif; }
+
+	/* show the second swash variant in h2 headings */
+	h2:first-letter { font-variant-alternates: swash(flowing); }
+
+	&lt;h2>Quick&lt;/h2></pre>
+
+	<p>When Jupiter Sans is present, the second alternate swash alternate will
+	be displayed. When not present, no swash character will be shown, since the
+	specific named value "flowing" is only defined for the Jupiter Sans family.
+	The @-mark indicates the name of the property value for which a named value
+	can be used.  The name "flowing" is chosen by the author.  The index that
+	represents each alternate is defined within a given font's data.</p>
+</div>
+
+<h4 id="font-feature-values-syntax">Basic syntax</h4>
+
+An ''@font-feature-values'' rule is composed of a list of
+font families followed by a block containing individual
+''feature value blocks'' that take the
+form of @-rules.  Each block defines a set of named values for a specific font feature
+when a given set of font families is used. Effectively, they define a mapping
+of &#x27e8;family, feature, ident&#x27e9; &rarr; &#x27e8;values&#x27e9;
+where &#x27e8;values&#x27e9; are the numeric indices used for specific
+features defined for a given font.
+
+<!-- Original (CSS2 syntax) text from Fonts 3, for checking
+
+
+<p>In terms of the grammar, this specification defines the following productions:</p>
+
+<pre><dfn>font_feature_values_rule</dfn>
+  : <i>FONT_FEATURE_VALUES_SYM</i> <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* <i>font_family_name_list</i> <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>*
+    '{' <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* <i>feature_value_block</i>? [ <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* <i>feature_value_block</i>? ]* '}' <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>*
+  ;
+
+<dfn>font_family_name_list</dfn>
+  : <i>font_family_name</i> [ <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* ',' <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* <i>font_family_name</i> ]*
+  ;
+
+<dfn>font_family_name</dfn>
+  : <a href="https://www.w3.org/TR/CSS21/syndata.html#tokenization"><i>STRING</i></a> | [ <a href="https://www.w3.org/TR/CSS21/syndata.html#tokenization"><i>IDENT</i></a> [ <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* <a href="https://www.w3.org/TR/CSS21/syndata.html#tokenization"><i>IDENT</i></a> ]* ]
+  ;
+
+<dfn>feature_value_block</dfn>
+  : <i>feature_type</i> <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>*
+    '{' <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* <i>feature_value_definition</i>? [ <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* ';' <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* <i>feature_value_definition</i>? ]* '}' <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>*
+  ;
+
+<dfn>feature_type</dfn>:
+  <a href="https://www.w3.org/TR/CSS21/syndata.html#tokenization"><i>ATKEYWORD</i></a>
+  ;
+
+<dfn>feature_value_definition</dfn>
+  : <a href="https://www.w3.org/TR/CSS21/syndata.html#tokenization"><i>IDENT</i></a> <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* ':' <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* <a href="https://www.w3.org/TR/css3-values/#integer-value"><i>&lt;integer&gt;</i></a> [ <a href="https://www.w3.org/TR/CSS21/grammar.html#scanner"><i>S</i></a>* <a href="https://www.w3.org/TR/css3-values/#integer-value"><i>&lt;integer&gt;</i></a> ]*
+  ;
+</pre>
+
+<p>The following new token is introduced:</p>
+
+<pre>@{F}{O}{N}{T}{-}{F}{E}{A}{T}{U}{R}{E}{-}{V}{A}{L}{U}{E}{S}   {return <dfn>FONT_FEATURE_VALUES_SYM</dfn>;}
+</pre>
+
+-->
+
+<pre class=prod>
+@font-feature-values = @font-feature-values &lt;family-name&gt;# { &lt;rule-list&gt; }
+
+&lt;family-name&gt; = &lt;string&gt; | &lt;custom-ident&gt;+
+
+&lt;feature-value-block&gt; = &lt;feature-type&gt; { &lt;declaration-list&gt; }
+
+&lt;feature-type&gt; = @stylistic | @historical-forms | @styleset | @character-variant
+	| @swash | @ornaments | @annotation
+
+&lt;feature-value&gt; = &lt;integer&gt;+
+</pre>
+
+Feature value blocks are handled as
+at-rules,
+they consist of everything up to the next block or
+semi-colon, whichever comes first.
+
+The font family list is a comma-delimited list of
+font family names that match the definition of &lt;family-name&gt;
+for the 'font-family!!property' property.
+This means that only named font families are allowed, rules that
+include generic or system fonts in the list of font families are
+syntax errors. However, if a user agent defines a generic font to be a
+specific named font (e.g. Helvetica), the settings associated with
+that family name will be used.  If syntax errors occur within the font
+family list, the entire rule must be ignored.
+
+Within feature value blocks,
+the feature type is '@' followed by the
+name of one of the <em>font specific</em> property values
+of 'font-variant-alternates' (e.g. ''@swash''). The
+identifiers used within feature value definitions follow the rules of
+CSS user identifiers and are case-sensitive. They are unique only for
+a given set of font families and feature type.
+The same identifier used with a different feature type
+is treated as a separate and distinct value.  If the same identifier is defined
+multiple times for a given feature type and font family,
+the last defined value is used. Values associated
+with a given identifier are limited to integer values 0 or greater.
+
+When syntax errors occur within a feature value
+definition, such as invalid identifiers or values, the entire feature value
+definition must be omitted, just as syntax errors in
+style declarations are handled.  When the feature type
+is invalid, the entire associated
+feature value block must be ignored.
+
+<div class="example">
+	<p>Rules that are equivalent given syntax error handling:</p>
+	<pre>@font-feature-values Bongo {
+	  @swash { ornate: 1; }
+	  annotation { boxed: 4; } /* should be @annotation! */
+	  @swash { double-loops: 1; flowing: -1; } /* negative value */
+	  @ornaments ; /* incomplete definition */
+	  @styleset { double-W: 14; sharp-terminals: 16 1 } /* missing ; */
+	  redrum  /* random editing mistake */
+	}</pre>
+
+	<p>The example above is equivalent to:</p>
+
+	<pre>@font-feature-values Bongo {
+	  @swash { ornate: 1; }
+	  @swash { double-loops: 1; }
+	  @styleset { double-W: 14; sharp-terminals: 16 1; }
+	}</pre>
+	</div>
+
+	<p>If multiple ''@font-feature-values'' rules are defined for
+	a given family, the resulting values definitions are the union of the
+	definitions contained within these rules. This allows a set of named
+	values to be defined for a given font family globally for a site and
+	specific additions made per-page.
+	</p>
+
+	<div class="example">
+	<p>Using both site-wide and per-page feature values:</p>
+	<pre>
+	site.css:
+
+	  @font-feature-values Mercury Serif {
+		@styleset {
+		  stacked-g: 3; /* "two-storey" versions of g, a */
+		  stacked-a: 4;
+		}
+	  }
+
+	page.css:
+
+	  @font-feature-values Mercury Serif {
+		@styleset {
+		  geometric-m: 7; /* alternate version of m */
+		}
+	  }
+
+	  body {
+		font-family: Mercury Serif, serif;
+
+		/* enable both the use of stacked g and alternate m */
+		font-variant-alternates: styleset(stacked-g, geometric-m);
+	  }</pre>
+	</div>
+
+	<div class="example">
+		<p>Using a commonly named value allows authors to use a single style rule
+		to cover a set of fonts for which the underlying selector is different for
+		each font. If either font in the example below is found, a circled number
+		glyph will be used:
+		</p>
+
+		<pre>@font-feature-values Taisho Gothic {
+		  @annotation { boxed: 1; circled: 4; }
+		}
+
+		@font-feature-values Otaru Kisa {
+		  @annotation { circled: 1; black-boxed: 3; }
+		}
+
+		h3.title {
+		  /* circled form defined for both fonts */
+		  font-family: Taisho Gothic, Otaru Kisa;
+		  font-variant: annotation(circled);
+		}</pre>
+		</div>
+
+	<h4>Multi-valued feature value definitions</h4>
+
+	Most <em>font specific</em> 'font-variant-alternates' property
+	values take a single value (e.g. 'swash'). The 'character-variant'
+	property value allows two values and 'styleset' allows an unlimited
+	number.
+
+	For the styleset property value, 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
+	<span class="tag">ss01</span> through <span class="tag">ss20</span>.
+	For OpenType fonts, values greater than 99 or equal to 0 do not
+	generate a syntax error when parsed but enable no OpenType features.
+
+
+<pre class="example">@font-feature-values Mars Serif {
+	@styleset {
+	alt-g: 1;        /* implies ss01 = 1 */
+	curly-quotes: 3; /* implies ss03 = 1 */
+	code: 4 5;       /* implies ss04 = 1, ss05 = 1 */
+	}
+
+	@styleset {
+	dumb: 125;        /* &gt;99, ignored */
+	}
+
+	@swash {
+	swishy: 3 5;     /* more than 1 value for swash, syntax error */
+	}
+}
+
+p.codeblock {
+	/* implies ss03 = 1, ss04 = 1, ss05 = 1 */
+	font-variant-alternates: styleset(curly-quotes, code);
+}</pre>
+
+	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
+	but enable no OpenType features. When two values are listed, the first
+	value indicates the feature used and the second the value passed for
+	that feature.  If more than two values are assigned to a given name, a
+	syntax error occurs and the entire
+	feature value definition</i> is
+	ignored.
+
+<pre class="example">@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 */
+	@character-variant { gamma: 12; }      /* implies cv12 = 1 */
+	@character-variant { zeta:   20 3; }   /* implies cv20 = 3 */
+	@character-variant { zeta-2: 20 2; }   /* implies cv20 = 2 */
+	@character-variant { silly: 105; }     /* &gt;99, ignored */
+	@character-variant { dumb: 323 3; }    /* &gt;99, ignored */
+}
+
+#title {
+	/* use the third alternate beta, first alternate gamma */
+	font-variant-alternates: character-variant(beta-3, gamma);
+}
+
+p {
+	/* zeta-2 follows zeta, implies cv20 = 2  */
+	font-variant-alternates: character-variant(zeta, zeta-2);
+}
+
+.special {
+	/* zeta follows zeta-2, implies cv20 = 3  */
+	font-variant-alternates: character-variant(zeta-2, zeta);
+}</pre>
+
+	<div class="figure"><img alt="Matching text on Byzantine seals using character variants" src="images/byzantineseal.png" /><p class="caption">Byzantine seal text displayed with character variants</p></div>
+
+	<div class="example">
+	<p>In the figure above, the text in red is rendered using a font containing
+	character variants that mimic the character forms found on a Byzantine seal
+	from the 8th century A.D.  Two lines below is the same text displayed in
+	a font without variants.  Note the two variants for U and N used on the
+	seal.</p>
+
+<pre>@font-feature-values Athena Ruby {
+	@character-variant {
+	leo-B: 2 1;
+	leo-M: 13 3;
+	leo-alt-N: 14 1;
+	leo-N: 14 2;
+	leo-T: 20 1;
+	leo-U: 21 2;
+	leo-alt-U: 21 4;
+	}
+}
+
+p {
+	font-variant: discretionary-ligatures
+				character-variant(leo-B, leo-M, leo-N, leo-T, leo-U);
+}
+
+span.alt-N {
+	font-variant-alternates: character-variant(leo-alt-N);
+}
+
+span.alt-U {
+	font-variant-alternates: character-variant(leo-alt-U);
+}
+
+&lt;p>ENO....UP͞RSTU&lt;span class="alt-U">U&lt;/span>͞&lt;span class="alt-U">U&lt;/span>ΚΑΙTỤẠG̣IUPNS&lt;/p>
+
+&lt;p>LEON|ΚΑΙCONSTA|NTI&lt;span class="alt-N">N&lt;/span>OS..|STOIBAṢ.|LIṢROM|AIO&lt;span class="alt-N">N&lt;/span>&lt;/p>
+</pre>
+	</div>
 
 <h3 id="font-variant-east-asian-prop">
 East Asian text rendering: the 'font-variant-east-asian' property</h3>
@@ -3771,7 +4094,7 @@ Preinstalled Fonts and User-Installed Fonts</h3>
 
 Users may choose to install fonts on their devices. User-Installed Fonts are installed by an explicit action by the user, such as clicking an "Install" button or copying a file into a particular directory on their device. Such fonts are User-Installed Fonts and also are Installed Fonts. Web content authors should not expect the presence of user-installed fonts, because there is no guarantee any user will have performed the action to install a specific font. User Agents may choose to ignore User-Installed Fonts for the purpose of the <a href="#font-matching-algorithm">Font Matching Algorithm</a>.
 
-Any Installed Font which is not a User-Installed font is a Preinstalled Font. It is likely that all users of a particular version of a particular Operating System will have the same set of Preinstalled Fonts installed. As such, Web content authors targetting these Operating Systems may wish to use these fonts' family names inside ''font-family'' properties.
+Any Installed Font which is not a User-Installed font is a Preinstalled Font. It is likely that all users of a particular version of a particular Operating System will have the same set of Preinstalled Fonts installed. As such, Web content authors targetting these Operating Systems may wish to use these fonts' family names inside 'font-family!!property' properties.
 
 <h3 id="system-font">
 System Font</h3>