Skip to content

Commit dfdd451

Browse files
fantasaifantasai
committed
[css-values-3] Align value definition gramar with L4
* Editorial tweaks for better structure and parallelism. * Define <func()> notation. * Define stacked multipliers.
1 parent f89e1a8 commit dfdd451

File tree

1 file changed

+65
-32
lines changed

1 file changed

+65
-32
lines changed

‎css-values-3/Overview.bs‎

Lines changed: 65 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -100,38 +100,64 @@ Component Value Types</h3>
100100

101101
Component value types are designated in several ways:
102102

103-
<ol>
104-
<li>
105-
<a href="#keywords">keyword</a> values (such as <css>auto</css>, ''disc'', etc.),
106-
which appear literally, without quotes (e.g. <code>auto</code>)
107-
108-
<li>
109-
basic data types, which appear between <css>&lt;</css> and <css>></css>
110-
(e.g., <<length>>, <<percentage>>, etc.).
111-
For <a>numeric data types</a>,
112-
this type notation can annotate any range restrictions
113-
using the [[#numeric-ranges|bracketed range notation]] described below.
114-
115-
<li>
116-
types that have the same range of values as a property bearing the same name
117-
(e.g., <<'border-width'>>, <<'background-attachment'>>, etc.).
118-
In this case, the type name is the property name (complete with quotes) between the brackets.
119-
Such a type does <em>not</em> include <a href="#common-keywords">CSS-wide keywords</a> such as ''inherit'',
120-
and also does not include any top-level <a href="#mult-comma">comma-separated-list multiplier</a>
121-
(i.e. if a property named <css>pairing</css> is defined as <css>[ <<custom-ident>> <<integer>>? ]#</css>,
122-
then <css>&lt;\'pairing'></css> is equivalent to <css>[ <<custom-ident>> <<integer>>? ]</css>,
123-
not <css>[ <<custom-ident>> <<integer>>? ]#</css>).
124-
125-
<li>
126-
non-terminals that do not share the same name as a property.
127-
In this case, the non-terminal name appears between <css>&lt;</css> and <css>></css>,
128-
as in <<spacing-limit>>.
129-
Notice the distinction between <<border-width>> and <<'border-width'>>:
130-
the latter is defined as the value of the 'border-width' property,
131-
the former requires an explicit expansion elsewhere.
132-
The definition of a non-terminal is typically located near its first appearance in the specification.
133-
</ol>
134-
103+
1. <a href="#keywords">Keyword</a> values (such as <css>auto</css>, ''disc'', etc.),
104+
which appear literally, without quotes (e.g. <code>auto</code>).
105+
106+
2. Basic data types,
107+
which appear between <css>&lt;</css> and <css>></css>
108+
(e.g., <<length>>, <<percentage>>, etc.).
109+
For <a>numeric data types</a>,
110+
this type notation can annotate any range restrictions
111+
using the [[#numeric-ranges|bracketed range notation]] described below.
112+
113+
3. Property value ranges,
114+
which represent the same pattern of values as a property bearing the same name.
115+
These are written as the property name,
116+
surrounded by single quotes,
117+
between <css>&lt;</css> and <css>></css>,
118+
e.g., <<'border-width'>>, <<'background-attachment'>>, etc.
119+
120+
These types <em>do not</em> include <a href="#common-keywords">CSS-wide keywords</a> such as ''inherit''.
121+
Additionally,
122+
if the property's value grammar
123+
is a <a lt=# grammar>comma-separated repetition</a>,
124+
the corresponding type
125+
does not include the top-level <a lt=# grammar>comma-separated list multiplier</a>.
126+
(E.g. if a property named <css>pairing</css> is defined as <css>[ <<custom-ident>> <<integer>>? ]#</css>,
127+
then <css>&lt;\'pairing'></css> is equivalent to <css>[ <<custom-ident>> <<integer>>? ]</css>,
128+
not <css>[ <<custom-ident>> <<integer>>? ]#</css>.)\
129+
130+
<details class=note>
131+
<summary>Why remove the multiplier?</summary>
132+
133+
The top-level multiplier is ripped out of these value types
134+
because top-level comma-separated repetitions are mostly used for
135+
[=coordinating list properties=],
136+
and when a shorthand combines several such properties,
137+
it needs the unmultiplied grammar
138+
so it can construct its <em>own</em> comma-separated repetition.
139+
140+
Without this special treatment,
141+
every such longhand would have to be defined
142+
with an ad-hoc production just for the inner value,
143+
which makes the grammars harder to understand overall.
144+
</details>
145+
146+
4. Functional notations and their arguments.
147+
These are written as the function's name,
148+
followed by an empty parentheses pair,
149+
between <css>&lt;</css> and <css>></css>,
150+
e.g. <<calc()>>,
151+
and references the correspondingly-named [=functional notation=].
152+
153+
5. Other non-terminals.
154+
These are written as the name of the non-terminal
155+
between <css>&lt;</css> and <css>></css>,
156+
as in <<spacing-limit>>.
157+
Notice the distinction between <<border-width>> and <<'border-width'>>:
158+
the latter represents the grammar of the 'border-width' property,
159+
the former requires an explicit expansion elsewhere.
160+
The definition of a non-terminal is typically located near its first appearance in the specification.
135161

136162
Some property value definitions also include the slash (/),
137163
the comma (,),
@@ -282,6 +308,13 @@ Component Value Multipliers</h3>
282308
at least one component value must not be omitted.
283309
</ul>
284310

311+
The <css>+</css> and <css>#</css> multipliers may be stacked as ''+#'';
312+
similarly, the <css>#</css> and <css>?</css> multipliers may be stacked as ''#?''.
313+
These stacks each represent the later multiplier
314+
applied to the result of the earlier multiplier.
315+
(These same stacks can be represented using grouping,
316+
but in complex grammars this can push the number of brackets beyond readability.)
317+
285318
For repeated component values (indicated by <css>*</css>, <css>+</css>, or <css>#</css>),
286319
[=UAs=] must support at least 20 repetitions of the component.
287320
If a property value contains more than the supported number of repetitions,

0 commit comments

Comments
 (0)