[css-syntax] More clarification.

Author: tabatkins

css-syntax/Overview.html

@@ -4484,45 +4484,25 @@ <h3 class="heading settled heading" data-level=8.1 id=style-rules><span class=se
 		but qualified rules inside <span class=css data-link-type=maybe title=@keyframes>@keyframes</span> rules are not <a data-biblio-type=informative data-link-type=biblio href=#css3-animations title=css3-animations>[CSS3-ANIMATIONS]</a>.
 
 <h3 class="heading settled heading" data-level=8.2 id=charset-rule><span class=secno>8.2 </span><span class=content>
-The <a class=css data-link-type=maybe href=#at-ruledef-charset title=@charset>@charset</a> Rule</span><a class=self-link href=#charset-rule></a></h3>
+The <span class=css data-link-type=maybe title=@charset>@charset</span> Rule</span><a class=self-link href=#charset-rule></a></h3>
 
-<p>	The <dfn class=css-code data-dfn-type=at-rule data-export="" id=at-ruledef-charset>@charset<a class=self-link href=#at-ruledef-charset></a></dfn> rule is a very special <a data-link-type=dfn href=#at-rule title=at-rule>at-rule</a> associated with determining the character encoding of the stylesheet.
-	In general, its grammar is:
+<p>	The @charset rule is an artifact of the algorithm used to <a data-link-type=dfn href=#determine-the-fallback-encoding title="determine the fallback encoding">determine the fallback encoding</a> for the stylesheet.
+	That algorithm looks for a specific byte sequence as the very first few bytes in the file,
+	which has the syntactic form of an @-rule.
+	Those bytes are not discarded from the input,
+	whether or not they influence the encoding actually used to process the stylesheet.
 
-<pre class=prod><dfn class=css-code data-dfn-type=type data-export="" id=typedef-at-charset-rule>&lt;at-charset-rule&gt;<a class=self-link href=#typedef-at-charset-rule></a></dfn> = @charset <a class="production css-code" data-link-type=type href=http://dev.w3.org/csswg/css-values-3/#string-value title="<string>">&lt;string&gt;</a>;</pre>
-<p>	Additionally, an <a class=css data-link-type=maybe href=#at-ruledef-charset title=@charset>@charset</a> rule is invalid if it is not at the top-level of a stylesheet,
-	or if it is not the very first rule of a stylesheet.
+<p>	Therefore, the stylesheet parser recognizes an @-rule with the general syntax
 
-<p>	<a class=css data-link-type=maybe href=#at-ruledef-charset title=@charset>@charset</a> rules have an <dfn data-dfn-type=dfn data-noexport="" id=at-charset-encoding>encoding<a class=self-link href=#at-charset-encoding></a></dfn>,
-	given by the value of the <a class="production css-code" data-link-type=type href=http://dev.w3.org/csswg/css-values-3/#string-value title="<string>">&lt;string&gt;</a>.
-
-<p>	The <a class=css data-link-type=maybe href=#at-ruledef-charset title=@charset>@charset</a> rule has <strong>no effect on a stylesheet</strong>.
-
-	<div class=note>
-		Confused?
-		Note that the preceding paragraph is talking about the <a class=css data-link-type=maybe href=#at-ruledef-charset title=@charset>@charset</a> <strong><a data-link-type=dfn href=#at-rule title=at-rule>at-rule</a></strong>.
-		CSS looks for a byte sequence that looks like "@charset" at the beginning of the document
-		to receive encoding enformation.
-		This is thematically similar to other encoding sequences at the beginning of files,
-		like a byte-order mark (BOM) hinting at the type of Unicode encoding used,
-		a DOCTYPE in an HTML document,
-		or a magic string like "MANIFEST" at the start of an HTML manifest.
-
-<p>		This byte sequence happens to <em>look</em> like a normal CSS rule, however,
-		and for legacy reasons,
-		that rule is reflected as an <a data-link-type=dfn href=#at-rule title=at-rule>at-rule</a> in the CSS Object Model <a data-biblio-type=informative data-link-type=biblio href=#cssom title=cssom>[CSSOM]</a>.
-		However, <strong>that at-rule object does nothing</strong>;
-		modifying it has no effect on the stylesheet,
-		nor does creating a fresh one and inserting it into a stylesheet.
-
-<p>		Note that some syntax that qualifies as a valid <a class=css data-link-type=maybe href=#at-ruledef-charset title=@charset>@charset</a> <a data-link-type=dfn href=#at-rule title=at-rule>at-rule</a>
-		is <strong>not</strong> a valid encoding declaration.
-		For example, since its argument is a string,
-		it can be written with single quotes around it.
-		This will create a valid <a class=css data-link-type=maybe href=#at-ruledef-charset title=@charset>@charset</a> rule,
-		but it won’t be recognized by the encoding detection step,
-		as it’s not the exact byte sequence that the algorithm requires.
-	</div>
+<pre class=prod><dfn class=css-code data-dfn-type=type data-export="" id=typedef-at-charset-rule>&lt;at-charset-rule&gt;<a class=self-link href=#typedef-at-charset-rule></a></dfn> = @charset <a class="production css-code" data-link-type=type href=http://dev.w3.org/csswg/css-values-3/#string-value title="<string>">&lt;string&gt;</a> ;</pre>
+<p>	and, for backward compatibility, includes it in the object model for the stylesheet.
+	Modifying, adding, or removing an @charset rule via the object model has no effect
+	(in particular it does *not* cause the stylesheet to be rescanned in a different encoding).
+	The @charset rule is invalid if it is not the very first, top-level rule in the stylesheet,
+	but it is parsed according to the normal syntax for @-rules,
+	which are less restrictive than the algorithm that determines the fallback encoding.
+	Therefore, an @charset rule may appear in the object model even if it was ignored by that algorithm.
+	(For instance, if it was written with extra whitespace or with single rather than double quotes.)
 
 
 
@@ -4737,10 +4717,10 @@ <h3 class="heading settled heading" data-level=10.3 id=changes-css21><span class
 
 <p>	<ul>
 		<li>
-			Only detect <a class=css data-link-type=maybe href=#at-ruledef-charset title=@charset>@charset</a> rules in ASCII-compatible byte patterns.
+			Only detect <span class=css data-link-type=maybe title=@charset>@charset</span> rules in ASCII-compatible byte patterns.
 
 		<li>
-			Ignore <a class=css data-link-type=maybe href=#at-ruledef-charset title=@charset>@charset</a> rules that specify an ASCII-incompatible encoding,
+			Ignore <span class=css data-link-type=maybe title=@charset>@charset</span> rules that specify an ASCII-incompatible encoding,
 			as that would cause the rule itself to not decode properly.
 
 		<li>
@@ -5027,7 +5007,6 @@ <h2 class="no-num no-ref heading settled heading" id=index><span class=content>
 <li>&lt;bad-url-token&gt;, <a href=#typedef-bad-url-token title="section 4">4</a>
 <li>&lt;CDC-token&gt;, <a href=#typedef-cdc-token title="section 4">4</a>
 <li>&lt;CDO-token&gt;, <a href=#typedef-cdo-token title="section 4">4</a>
-<li>@charset, <a href=#at-ruledef-charset title="section 8.2">8.2</a>
 <li>check if three code points would start an identifier, <a href=#check-if-three-code-points-would-start-an-identifier title="section 4.3.9">4.3.9</a>
 <li>check if three code points would start a number, <a href=#check-if-three-code-points-would-start-a-number title="section 4.3.10">4.3.10</a>
 <li>check if two code points are a valid escape, <a href=#check-if-two-code-points-are-a-valid-escape title="section 4.3.8">4.3.8</a>
@@ -5066,7 +5045,6 @@ <h2 class="no-num no-ref heading settled heading" id=index><span class=content>
 <li>determine the fallback encoding, <a href=#determine-the-fallback-encoding title="section 3.2">3.2</a>
 <li>digit, <a href=#digit title="section 4.2">4.2</a>
 <li>&lt;dimension-token&gt;, <a href=#typedef-dimension-token title="section 4">4</a>
-<li>encoding, <a href=#at-charset-encoding title="section 8.2">8.2</a>
 <li>ending token, <a href=#ending-token title="section 5.4.7">5.4.7</a>
 <li>end of the range, <a href=#unicode-range-end title="section 4">4</a>
 <li>environment encoding, <a href=#environment-encoding0 title="section 3.3">3.3</a>

css-syntax/Overview.src.html

@@ -3011,44 +3011,24 @@ <h3 id="style-rules">
 <h3 id='charset-rule'>
 The ''@charset'' Rule</h3>
 
-	The <dfn>@charset</dfn> rule is a very special <i>at-rule</i> associated with determining the character encoding of the stylesheet.
-	In general, its grammar is:
-
-	<pre class='prod'><dfn>&lt;at-charset-rule></dfn> = @charset <<string>>;</pre>
-
-	Additionally, an ''@charset'' rule is invalid if it is not at the top-level of a stylesheet,
-	or if it is not the very first rule of a stylesheet.
-
-	''@charset'' rules have an <dfn id="at-charset-encoding">encoding</dfn>,
-	given by the value of the <<string>>.
-
-	The ''@charset'' rule has <strong>no effect on a stylesheet</strong>.
-
-	<div class='note'>
-		Confused?
-		Note that the preceding paragraph is talking about the ''@charset'' <strong><a>at-rule</a></strong>.
-		CSS looks for a byte sequence that looks like "@charset" at the beginning of the document
-		to receive encoding enformation.
-		This is thematically similar to other encoding sequences at the beginning of files,
-		like a byte-order mark (BOM) hinting at the type of Unicode encoding used,
-		a DOCTYPE in an HTML document,
-		or a magic string like "MANIFEST" at the start of an HTML manifest.
-
-		This byte sequence happens to <em>look</em> like a normal CSS rule, however,
-		and for legacy reasons,
-		that rule is reflected as an <a>at-rule</a> in the CSS Object Model [[CSSOM]].
-		However, <strong>that at-rule object does nothing</strong>;
-		modifying it has no effect on the stylesheet,
-		nor does creating a fresh one and inserting it into a stylesheet.
-
-		Note that some syntax that qualifies as a valid ''@charset'' <a>at-rule</a>
-		is <strong>not</strong> a valid encoding declaration.
-		For example, since its argument is a string,
-		it can be written with single quotes around it.
-		This will create a valid ''@charset'' rule,
-		but it won't be recognized by the encoding detection step,
-		as it's not the exact byte sequence that the algorithm requires.
-	</div>
+	The @charset rule is an artifact of the algorithm used to <a>determine the fallback encoding</a> for the stylesheet.
+	That algorithm looks for a specific byte sequence as the very first few bytes in the file,
+	which has the syntactic form of an @-rule.
+	Those bytes are not discarded from the input,
+	whether or not they influence the encoding actually used to process the stylesheet.
+
+	Therefore, the stylesheet parser recognizes an @-rule with the general syntax
+
+	<pre class='prod'><dfn>&lt;at-charset-rule></dfn> = @charset <<string>> ;</pre>
+
+	and, for backward compatibility, includes it in the object model for the stylesheet.
+	Modifying, adding, or removing an @charset rule via the object model has no effect
+	(in particular it does *not* cause the stylesheet to be rescanned in a different encoding).
+	The @charset rule is invalid if it is not the very first, top-level rule in the stylesheet,
+	but it is parsed according to the normal syntax for @-rules,
+	which are less restrictive than the algorithm that determines the fallback encoding.
+	Therefore, an @charset rule may appear in the object model even if it was ignored by that algorithm.
+	(For instance, if it was written with extra whitespace or with single rather than double quotes.)