Skip to content

Commit d0b6081

Browse files
SimonSapinSimonSapin
committed
[css-syntax] Make the details of serialization non-normative.
The normative requirement is "round-tripping". The explanations on how to achieve it are now non-normative.
1 parent 20f6bfb commit d0b6081

2 files changed

Lines changed: 502 additions & 80 deletions

File tree

‎css-syntax/Overview.html‎

Lines changed: 251 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
</a></p>
1313
<h1 class="p-name no-ref" id=title>CSS Syntax Module Level 3</h1>
1414
<h2 class="no-num no-toc no-ref heading settled heading" id=subtitle><span class=content>Editor’s Draft,
15-
<span class=dt-updated><span class=value-title title=20131031>31 October 2013</span></span></span></h2>
15+
<span class=dt-updated><span class=value-title title=20131101>1 November 2013</span></span></span></h2>
1616
<div data-fill-with=spec-metadata><dl><dt>This version:<dd><a class=u-url href=http://dev.w3.org/csswg/css-syntax/>http://dev.w3.org/csswg/css-syntax/</a><dt>Latest version:<dd><a href=http://www.w3.org/TR/css-syntax-3/>http://www.w3.org/TR/css-syntax-3/</a><dt>Editor’s Draft:<dd><a href=http://dev.w3.org/csswg/css-syntax/>http://dev.w3.org/csswg/css-syntax/</a><dt>Previous Versions:<dd><a href=http://www.w3.org/TR/2013/WD-css-syntax-3-20130919/ rel=previous>http://www.w3.org/TR/2013/WD-css-syntax-3-20130919/</a>
1717
<dt>Feedback:</dt>
1818
<dd><a href="mailto:www-style@w3.org?subject=%5Bcss-syntax%5D%20feedback">www-style@w3.org</a>
@@ -4455,55 +4455,266 @@ <h3 class="heading settled heading" data-level=8.2 id=charset-rule><span class=s
44554455
<h2 class="heading settled heading" data-level=9 id=serialization><span class=secno>9 </span><span class=content>
44564456
Serialization</span><a class=self-link href=#serialization></a></h2>
44574457

4458-
<p> This specification does not define how to serialize CSS in general,
4459-
leaving that task to the CSSOM and individual feature specifications.
4460-
However, there is one important facet that must be specified here regarding comments,
4461-
to ensure accurate "round-tripping" of data from text to CSS objects and back.
4462-
44634458
<p> The tokenizer described in this specification does not produce tokens for comments,
44644459
or otherwise preserve them in any way.
44654460
Implementations may preserve the contents of comments and their location in the token stream.
4466-
If they do, this preserved information must have no effect on the parsing step,
4467-
but must be serialized in its position as
4468-
"/*"
4469-
followed by its contents
4470-
followed by "*/".
4461+
If they do, this preserved information must have no effect on the parsing step.
44714462

4472-
<p> Unless the implementation has a preserved comment at that position,
4473-
it must insert the text "/**/" between the serialization of adjacent tokens
4474-
when the two tokens are of the following pairs:
4475-
4476-
<p> <ul>
4477-
<li>
4478-
a <a class="production css-code" data-link-type=type href=#typedef-hash-token title="<hash-token>">&lt;hash-token&gt;</a> or <a class="production css-code" data-link-type=type href=#typedef-at-keyword-token title="<at-keyword-token>">&lt;at-keyword-token&gt;</a> followed by a <a class="production css-code" data-link-type=type href=#typedef-number-token title="<number-token>">&lt;number-token&gt;</a>, <a class="production css-code" data-link-type=type href=#typedef-percentage-token title="<percentage-token>">&lt;percentage-token&gt;</a>, <a class="production css-code" data-link-type=type href=#typedef-ident-token title="<ident-token>">&lt;ident-token&gt;</a>, <a class="production css-code" data-link-type=type href=#typedef-dimension-token title="<dimension-token>">&lt;dimension-token&gt;</a>, <a class="production css-code" data-link-type=type href=#typedef-unicode-range-token title="<unicode-range-token>">&lt;unicode-range-token&gt;</a>, <a class="production css-code" data-link-type=type href=#typedef-url-token title="<url-token>">&lt;url-token&gt;</a>, or a <a class="production css-code" data-link-type=type href=#typedef-function-token title="<function-token>">&lt;function-token&gt;</a>;
4479-
4480-
<li>
4481-
<a class="production css-code" data-link-type=type href=#typedef-number-token title="<number-token>">&lt;number-token&gt;</a>s, <a class="production css-code" data-link-type=type href=#typedef-ident-token title="<ident-token>">&lt;ident-token&gt;</a>s, and <a class="production css-code" data-link-type=type href=#typedef-dimension-token title="<dimension-token>">&lt;dimension-token&gt;</a>s in any combination;
4482-
4483-
<li>
4484-
a <a class="production css-code" data-link-type=type href=#typedef-number-token title="<number-token>">&lt;number-token&gt;</a>, <a class="production css-code" data-link-type=type href=#typedef-ident-token title="<ident-token>">&lt;ident-token&gt;</a>, or <a class="production css-code" data-link-type=type href=#typedef-dimension-token title="<dimension-token>">&lt;dimension-token&gt;</a> followed by a <a class="production css-code" data-link-type=type href=#typedef-percentage-token title="<percentage-token>">&lt;percentage-token&gt;</a>, <a class="production css-code" data-link-type=type href=#typedef-unicode-range-token title="<unicode-range-token>">&lt;unicode-range-token&gt;</a>, <a class="production css-code" data-link-type=type href=#typedef-url-token title="<url-token>">&lt;url-token&gt;</a>, or <a class="production css-code" data-link-type=type href=#typedef-function-token title="<function-token>">&lt;function-token&gt;</a>;
4463+
<p> This specification does not define how to serialize CSS in general,
4464+
leaving that task to the CSSOM and individual feature specifications.
4465+
In particular, the serialization of comments an whitespace is not defined.
44854466

4486-
<li>
4487-
an <a class="production css-code" data-link-type=type href=#typedef-ident-token title="<ident-token>">&lt;ident-token&gt;</a> followed by a <a href=#tokendef-open-paren>&lt;(-token&gt;</a>;
4467+
<p> The only requirement for serialization is that it must "round-trip" with parsing,
4468+
ie. parsing again the serialized output must result in identical tokens or other structures,
4469+
except for consecutive <a class="production css-code" data-link-type=type href=#typedef-whitespace-token title="<whitespace-token>">&lt;whitespace-token&gt;</a>s
4470+
that may be collapsed into a single token.
44884471

4489-
<li>
4490-
a <a class="production css-code" data-link-type=type href=#typedef-delim-token title="<delim-token>">&lt;delim-token&gt;</a> containing "#" or "@" followed by any token except <a class="production css-code" data-link-type=type href=#typedef-whitespace-token title="<whitespace-token>">&lt;whitespace-token&gt;</a>;
4472+
<p class=note> Note: This exception can exist because
4473+
CSS grammars always interpret any amount of whitespace as identical to a single space.
44914474

4492-
<li>
4493-
a <a class="production css-code" data-link-type=type href=#typedef-delim-token title="<delim-token>">&lt;delim-token&gt;</a> containing "-", "+", ".", "&lt;", "&gt;", or "!" following or followed by any token except <a class="production css-code" data-link-type=type href=#typedef-whitespace-token title="<whitespace-token>">&lt;whitespace-token&gt;</a>;
4475+
<div class=note id=serialization-tables><style scoped>
4476+
#serialization-tables table { margin: 1em 0 }
4477+
#serialization-tables table { border-collapse: collapse }
4478+
#serialization-tables tr:nth-child(even) { background: rgba(0, 0, 0, .1) }
4479+
#serialization-tables th { padding: .2em .5em; line-height: 1.1 }
4480+
#serialization-tables th, td { text-align: center }
4481+
</style>
44944482

4495-
<li>
4496-
a <a class="production css-code" data-link-type=type href=#typedef-delim-token title="<delim-token>">&lt;delim-token&gt;</a> containing "/" following or followed by a <a class="production css-code" data-link-type=type href=#typedef-delim-token title="<delim-token>">&lt;delim-token&gt;</a> containing "*".
4497-
</ul>
4483+
<a class=self-link href=#serialization-tables></a>
4484+
Note: In order to satisfy this requirement:
44984485

4499-
<p class=note> Note: The preceding pairs of tokens can only be adjacent due to comments in the original text,
4500-
so the above rule reinserts the minimum number of comments into the serialized text to ensure an accurate round-trip.
4501-
(Roughly. The <a class="production css-code" data-link-type=type href=#typedef-delim-token title="<delim-token>">&lt;delim-token&gt;</a> rules are slightly too powerful, for simplicity.)
4486+
<p> <ul>
4487+
<li>
4488+
A <a class="production css-code" data-link-type=type href=#typedef-delim-token title="<delim-token>">&lt;delim-token&gt;</a> containing U+005C REVERSE SOLIDUS (\)
4489+
must be followed when serialized by a <a data-link-type=dfn href=#newline title=newline>newline</a>.
4490+
(The tokenizer only ever emits such a token followed by a <a class="production css-code" data-link-type=type href=#typedef-whitespace-token title="<whitespace-token>">&lt;whitespace-token&gt;</a>
4491+
that starts with a newline.)
4492+
<li>
4493+
Consecutive pairs of tokens that have a ✓ in either of the two tables below
4494+
must be serialized with a comment in-between.
4495+
If no comment was preserved from tokenization,
4496+
an empty comment <code>/**/</code> should be inserted.
4497+
Rows and columns represent a token and its following token, respectively.
4498+
Single character represent a <a class="production css-code" data-link-type=type href=#typedef-delim-token title="<delim-token>">&lt;delim-token&gt;</a> with that value,
4499+
except for "<code>(</code>" that
4500+
represents a <a href=#tokendef-open-paren>(-token</a>.
4501+
</ul>
45024502

4503-
<p class=note> Note: No comment is inserted between consecutive <a class="production css-code" data-link-type=type href=#typedef-whitespace-token title="<whitespace-token>">&lt;whitespace-token&gt;</a>.
4504-
As a consequence such token sequences will not "round-trip" exactly.
4505-
This shouldn’t be an issue as CSS grammars always interpret
4506-
any amount of whitespace as identical to a single space.
4503+
<table>
4504+
<tr>
4505+
<td></td>
4506+
<th>ident</th>
4507+
<th>function</th>
4508+
<th>url</th>
4509+
<th>bad-url</th>
4510+
<th>-</th>
4511+
<th>number</th>
4512+
<th>percentage</th>
4513+
<th>dimension</th>
4514+
<th>unicode-range</th>
4515+
<th>CDC</th>
4516+
<th>(</th>
4517+
</tr>
4518+
<tr>
4519+
<th>ident</th>
4520+
<td>✓</td>
4521+
<td>✓</td>
4522+
<td>✓</td>
4523+
<td>✓</td>
4524+
<td>✓</td>
4525+
<td>✓</td>
4526+
<td>✓</td>
4527+
<td>✓</td>
4528+
<td>✓</td>
4529+
<td>✓</td>
4530+
<td>✓</td>
4531+
</tr>
4532+
<tr>
4533+
<th>at-keyword</th>
4534+
<td>✓</td>
4535+
<td>✓</td>
4536+
<td>✓</td>
4537+
<td>✓</td>
4538+
<td>✓</td>
4539+
<td>✓</td>
4540+
<td>✓</td>
4541+
<td>✓</td>
4542+
<td>✓</td>
4543+
<td>✓</td>
4544+
<td></td>
4545+
</tr>
4546+
<tr>
4547+
<th>hash</th>
4548+
<td>✓</td>
4549+
<td>✓</td>
4550+
<td>✓</td>
4551+
<td>✓</td>
4552+
<td>✓</td>
4553+
<td>✓</td>
4554+
<td>✓</td>
4555+
<td>✓</td>
4556+
<td>✓</td>
4557+
<td>✓</td>
4558+
<td></td>
4559+
</tr>
4560+
<tr>
4561+
<th>dimension</th>
4562+
<td>✓</td>
4563+
<td>✓</td>
4564+
<td>✓</td>
4565+
<td>✓</td>
4566+
<td>✓</td>
4567+
<td>✓</td>
4568+
<td>✓</td>
4569+
<td>✓</td>
4570+
<td>✓</td>
4571+
<td>✓</td>
4572+
<td></td>
4573+
</tr>
4574+
<tr>
4575+
<th>#</th>
4576+
<td>✓</td>
4577+
<td>✓</td>
4578+
<td>✓</td>
4579+
<td>✓</td>
4580+
<td>✓</td>
4581+
<td>✓</td>
4582+
<td>✓</td>
4583+
<td>✓</td>
4584+
<td>✓</td>
4585+
<td></td>
4586+
<td></td>
4587+
</tr>
4588+
<tr>
4589+
<th>-</th>
4590+
<td>✓</td>
4591+
<td>✓</td>
4592+
<td>✓</td>
4593+
<td>✓</td>
4594+
<td></td>
4595+
<td>✓</td>
4596+
<td>✓</td>
4597+
<td>✓</td>
4598+
<td>✓</td>
4599+
<td></td>
4600+
<td></td>
4601+
</tr>
4602+
<tr>
4603+
<th>number</th>
4604+
<td>✓</td>
4605+
<td>✓</td>
4606+
<td>✓</td>
4607+
<td>✓</td>
4608+
<td></td>
4609+
<td>✓</td>
4610+
<td>✓</td>
4611+
<td>✓</td>
4612+
<td>✓</td>
4613+
<td></td>
4614+
<td></td>
4615+
</tr>
4616+
<tr>
4617+
<th>@</th>
4618+
<td>✓</td>
4619+
<td>✓</td>
4620+
<td>✓</td>
4621+
<td>✓</td>
4622+
<td>✓</td>
4623+
<td></td>
4624+
<td></td>
4625+
<td></td>
4626+
<td>✓</td>
4627+
<td></td>
4628+
<td></td>
4629+
</tr>
4630+
<tr>
4631+
<th>unicode-range</th>
4632+
<td>✓</td>
4633+
<td>✓</td>
4634+
<td></td>
4635+
<td></td>
4636+
<td></td>
4637+
<td>✓</td>
4638+
<td>✓</td>
4639+
<td>✓</td>
4640+
<td></td>
4641+
<td></td>
4642+
<td></td>
4643+
</tr>
4644+
<tr>
4645+
<th>.</th>
4646+
<td></td>
4647+
<td></td>
4648+
<td></td>
4649+
<td></td>
4650+
<td></td>
4651+
<td>✓</td>
4652+
<td>✓</td>
4653+
<td>✓</td>
4654+
<td></td>
4655+
<td></td>
4656+
<td></td>
4657+
</tr>
4658+
<tr>
4659+
<th>+</th>
4660+
<td></td>
4661+
<td></td>
4662+
<td></td>
4663+
<td></td>
4664+
<td></td>
4665+
<td>✓</td>
4666+
<td>✓</td>
4667+
<td>✓</td>
4668+
<td></td>
4669+
<td></td>
4670+
<td></td>
4671+
</tr>
4672+
</table>
4673+
4674+
<table>
4675+
<tr>
4676+
<td></td>
4677+
<th>=</th>
4678+
<th>|</th>
4679+
<th>*</th>
4680+
<tr>
4681+
<th>$</th>
4682+
<td>✓</td>
4683+
<td></td>
4684+
<td></td>
4685+
</tr>
4686+
<tr>
4687+
<th>*</th>
4688+
<td>✓</td>
4689+
<td></td>
4690+
<td></td>
4691+
</tr>
4692+
<tr>
4693+
<th>^</th>
4694+
<td>✓</td>
4695+
<td></td>
4696+
<td></td>
4697+
</tr>
4698+
<tr>
4699+
<th>~</th>
4700+
<td>✓</td>
4701+
<td></td>
4702+
<td></td>
4703+
</tr>
4704+
<tr>
4705+
<th>|</th>
4706+
<td>✓</td>
4707+
<td>✓</td>
4708+
<td></td>
4709+
</tr>
4710+
<tr>
4711+
<th>/</th>
4712+
<td></td>
4713+
<td></td>
4714+
<td>✓</td>
4715+
</tr>
4716+
</table>
4717+
</div>
45074718

45084719
<h3 class="heading settled heading" data-level=9.1 id=serializing-anb><span class=secno>9.1 </span><span class=content>
45094720
Serializing <var>&lt;an+b&gt;</var></span><a class=self-link href=#serializing-anb></a></h3>

0 commit comments

Comments
 (0)