Use bracket range notation in syntax grammar [css-values-3][css… (w3c…

…#3894)

* [css-values-3] Tidy bracket range definition

- Fix incorrect heading level & a typo from
  8ea8d7d
- Add examples converting the notation to prose.

* [css-values-4] Copy over bracket range definition

These changes were added to Level 3 in
8ea8d7d
and
1265976

(And fix a tabs-vs-spaces error that bikeshed was choking on.)

* [css-backgrounds-3][css-backgrounds-4] Use bracketed range notation

Added bracketed range notation for non-negative values ( [0,∞] )
in these properties & productions:

- <bg-size>
- <line-width>
- border-radius and longhands
- border-image-slice
- border-image-width
- border-image-outset
- <shadow>
  NOTE: required re-writing the syntax
  (since ony one of the 4 possible lengths has a restriction)
- border-limit and border-clip in level 4
  NOTE: these didn't have prose restrictions,
  but they also didn't explain how negative values could work.

I added a changes note to level 3 (change since CR),
but not level 4 (not published yet).

* [css-values-3][css-values-4] Export dfn for  bracketed range notation

* [css-multicol-1][css-multicol-2] Use bracketed range notation

Added bracketed range notation for non-negative values ( [0,∞] )
or strictly positive integers ( [1,∞] )
in these properties:

- column-width
- column-count
- column-gap
- column-span (level 2)

For column-rule-width, the syntax change was made
for the `<line-width>` production,
in 933d7dd

* [css-flexbox-1] Use bracketed range notation

Added bracketed range notation for non-negative values ( [0,∞] )
in these properties:

- flex-grow
- flex-shrink

Also use it in the prose descriptions for `flex`,
and to replace the made up `<postive-number>` variable
in the examples of common patterns.

Created a new "Changes since the 19 November 2018 CR" section
to include a mention of the update.

The syntax for `flex-basis` will be updated by reference
when `width` is updated.

* [css-counter-styles-3] Use bracketed range notation

Added bracketed range notation for non-negative values ( [0,∞] )
in the following descriptors:

- pad
- additive-symbols

Note: I didn't add any restriction to the integer
in the `system: fixed <integer>` descriptor,
since there was no prose constraint.
But I'm not sure that negative values make sense here.

* Standardize prose for constrained values [css-backgrounds-3][css-counter-styles-3][css-flexbox-1][css-multicol-1][css-values-3][css-values-4]

For all the specs covered by PR w3c#3894.

<<type [0,&infin;]>>
→ “Negative values are not allowed.”

<<integer [1, &infin;]>>
→ “Values must be greater than 0.”

And remove some duplicate phrases.

Added these phrases & the other most commonly used one (“are invalid”)
to the note in CSS Values about prose restrictions.

* [css-values-3][css-values-4] Fix broken entity

Co-authored-by: Tab Atkins Jr <[email protected]>

css-backgrounds-3/Overview.bs

@@ -924,7 +924,7 @@ layer.
 
 <p>Specifies the size of the background images. Where
 
-<pre class=prod><dfn><<bg-size>></dfn> = [ <<length-percentage>> | auto ]{1,2} | cover | contain</pre>
+<pre class=prod><dfn><<bg-size>></dfn> = [ <<length-percentage [0,&infin;]>> | auto ]{1,2} | cover | contain</pre>
 
 <p>Values have the following meanings:
 
@@ -940,7 +940,7 @@ layer.
     (if any), to the smallest size such that both its width and its
     height can completely cover the background positioning area.</dd>
 
-  <dt>[ <dfn><<length-percentage>></dfn>
+  <dt>[ <dfn><<length-percentage [0,&infin;]>></dfn>
   | <dfn>auto</dfn> ]{1,2}</dt>
   <dd>
     <p>The first value gives the width of the corresponding image,
@@ -1633,15 +1633,15 @@ the padding is less than the radius of the corner.
 <p>These properties set the thickness of the border.
 Where
 
-<pre class=prod><dfn><<line-width>></dfn> = <<length>> | thin | medium | thick</pre>
+<pre class=prod><dfn><<line-width>></dfn> = <<length [0,&infin;]>> | thin | medium | thick</pre>
 
 <p dfn-type=value dfn-for="<line-width>, border-width, border-top-width, border-left-width, border-bottom-width, border-right-width, border">
 The lengths corresponding to <dfn>thin</dfn>, <dfn>medium</dfn>, and <dfn>thick</dfn>
 are not specified, but the values are constant throughout a
 <span>document</span> and thin &le; medium &le; thick. A UA could,
 e.g., make the thickness depend on the ''medium'' font size: one
 choice might be 1, 3 &amp; 5px when the ''medium'' font size is 17px or
-less. Negative <<length>> values are not allowed.
+less. Negative values are not allowed.
 
 <p>'Border-width' is a shorthand that sets the
 four 'border-*-width' properties. If it has four values, they set top, right,
@@ -1793,7 +1793,7 @@ the 'color' property. The fact that the
         <dfn>border-bottom-left-radius</dfn>
     <tr>
     <th><a href="#values">Value</a>:
-    <td><<length-percentage>>{1,2}
+    <td><<length-percentage [0,&infin;]>>{1,2}
   <tr>
     <th>Initial:
     <td>0
@@ -1821,7 +1821,7 @@ the 'color' property. The fact that the
     <td><dfn>border-radius</dfn>
   <tr>
     <th><a href="#values">Value</a>:
-    <td><<length-percentage>>{1,4} [ / <<length-percentage>>{1,4} ]?
+    <td><<length-percentage [0,&infin;]>>{1,4} [ / <<length-percentage [0,&infin;]>>{1,4} ]?
   <tr>
     <th>Initial:
     <td>see individual properties
@@ -2233,7 +2233,7 @@ and the border image is drawn as described in the sections below.
     <td><dfn>border-image-slice</dfn>
   <tr>
     <th><a href="#values">Value</a>:
-    <td>[<<number>> | <<percentage>>]{1,4} &amp;&amp; fill?
+    <td>[<<number [0,&infin;]>> | <<percentage [0,&infin;]>>]{1,4} &amp;&amp; fill?
   <tr>
     <th>Initial:
     <td>100%
@@ -2268,12 +2268,12 @@ the same as the right; if the bottom is missing, it is the same as the top;
 if the right is missing, it is the same as the top.
 
 <dl dfn-for=border-image-slice dfn-type=value>
-  <dt><dfn><<percentage>></dfn>
+  <dt><dfn><<percentage [0,&infin;]>></dfn>
   <dd>Percentages are relative to the size of the image: the width
     of the image for the horizontal offsets, the height for vertical
     offsets.
 
-  <dt><dfn><<number>></dfn>
+  <dt><dfn><<number [0,&infin;]>></dfn>
   <dd>Numbers represent pixels in the image (if the image is a raster
     image) or vector coordinates (if the image is a vector image).
 
@@ -2283,7 +2283,7 @@ if the right is missing, it is the same as the top.
     i.e., treated as empty.)
 </dl>
 
-<p>Negative values are invalid.
+<p>Negative values are not allowed.
 Computed values larger than the size of the image are interpreted as ''100%''.
 
 <p>The regions given by the 'border-image-slice' values may overlap.
@@ -2314,7 +2314,7 @@ with no <i>specified size</i> and the <i>border image area</i> as the <i>default
     <td><dfn>border-image-width</dfn>
   <tr>
     <th><a href="#values">Value</a>:
-    <td>[ <<length-percentage>> | <<number>> | auto ]{1,4}
+    <td>[ <<length-percentage [0,&infin;]>> | <<number [0,&infin;]>> | auto ]{1,4}
   <tr>
     <th>Initial:
     <td>1
@@ -2348,11 +2348,11 @@ if the bottom is missing, it is the same as the top; if the right is missing,
 it is the same as the top. Values have the following meanings:</p>
 
 <dl dfn-for=border-image-width dfn-type=value>
-  <dt><dfn><<length-percentage>></dfn>
+  <dt><dfn><<length-percentage [0,&infin;]>></dfn>
   <dd>Percentages refer to the size of the border image area: the width of the
     area for horizontal offsets, the height for vertical offsets.
 
-  <dt><dfn><<number>></dfn>
+  <dt><dfn><<number [0,&infin;]>></dfn>
   <dd>Numbers represent multiples of the corresponding computed
     <a href="#the-border-width">border-width</a>.
 
@@ -2387,7 +2387,7 @@ them by <var>f</var>.
     <td><dfn>border-image-outset</dfn>
   <tr>
     <th><a href="#values">Value</a>:
-    <td>[ <<length>> | <<number>> ]{1,4}
+    <td>[ <<length [0,&infin;]>> | <<number [0,&infin;]>> ]{1,4}
   <tr>
     <th>Initial:
     <td>0
@@ -2417,15 +2417,15 @@ if the bottom is missing, it is the same as the top; if the right is missing,
 it is the same as the top.
 
 <dl dfn-for=border-image-outset dfn-type=value>
-  <dt><<length>>
+  <dt><<length [0,&infin;]>>
   <dd>Represents an outset of the specified length.
-  Negative values are invalid.
 
-  <dt><<number>>
+  <dt><<number [0,&infin;]>>
   <dd>Represents an outset of the specified multiple of the corresponding computed <a href="#the-border-width">border-width</a>.
-  Negative values are invalid.
 </dl>
 
+<p>Negative values are not allowed.
+
 <p>Portions of the border-image that are rendered outside the border
 box do not trigger scrolling. Also such portions are invisible to mouse
 events and do not capture such events on behalf of the element.</p>
@@ -2671,7 +2671,7 @@ has been moved to the <a href="https://www.w3.org/TR/css3-break/">CSS Fragmentat
   represented by 2-4 length values, an optional color, and an optional ''box-shadow/inset'' keyword.
   Omitted lengths are 0; omitted colors default to the value of the 'color' property.
   <pre class=prod>
-  <dfn><<shadow>></dfn> = <<color>>? &amp;&amp; <<length>>{2,4} &amp;&amp; inset?</pre>
+  <dfn><<shadow>></dfn> = <<color>>? &amp;&amp; [<<length>>{2} <<length [0,&infin;]>>? <<length>>?] &amp;&amp; inset?</pre>
 
   <p>The components of each <<shadow>> are interpreted as follows:
 
@@ -2687,7 +2687,7 @@ has been moved to the <a href="https://www.w3.org/TR/css3-break/">CSS Fragmentat
       Specifies the <dfn>vertical offset</dfn> of the shadow.
       A positive value offsets the shadow down, a negative one up.
 
-    <dt><dfn id="shadow-blur-radius">3rd <<length>></dfn>
+    <dt><dfn id="shadow-blur-radius">3rd <<length [0,&infin;]>></dfn>
     <dd>Specifies the <dfn>blur radius</dfn>.
       Negative values are not allowed.
       If the blur value is zero, the shadow’s edge is sharp.
@@ -3020,6 +3020,9 @@ Changes since the 17 October 2017 Candidate Recommendation</h3>
   <li>
     Cleaned up and regularized “Animation type” and “Computed value” lines
     in the property definition tables.
+  <li>
+    Changed syntax to use <a>bracketed range notation</a>
+    to reflect the prose restrictions on negative values.
 </ul>
 
 <h3 id="changes-2014-09">

css-backgrounds-4/Overview.bs

@@ -241,7 +241,7 @@ Corner Sizing: the 'border-radius property</h3>
 
 	<pre class="propdef">
 		Name: border-radius
-		Value: <<length-percentage>>{1,4} [ / <<length-percentage>>{1,4} ]?
+		Value: <<length-percentage [0,&infin;]>>{1,4} [ / <<length-percentage [0,&infin;]>>{1,4} ]?
 		Initial: 0
 		Applies to: all elements, except table element when 'border-collapse' is ''collapse''
 		Inherited: no
@@ -357,8 +357,8 @@ Partial Borders: the 'border-limit' property</h3>
 
 	<pre class="propdef">
   	Name: border-limit
-  	Value: all | [ sides | corners ] <<length-percentage>>?
-  				| [ top | right | bottom | left ] <<length-percentage>>
+  	Value: all | [ sides | corners ] <<length-percentage [0,&infin;]>>?
+  				| [ top | right | bottom | left ] <<length-percentage [0,&infin;]>>
   	Initial: round
   	Applies to: all elements, except table element when 'border-collapse' is ''collapse''
   	Inherited: no
@@ -413,7 +413,7 @@ The 'border-clip' properties</h3>
 
 		<pre class="propdef">
   		Name: border-clip, border-clip-top, border-clip-right, border-clip-bottom, border-clip-left
-  		Value: normal | [ <<length-percentage>> | <<flex>> ]+
+  		Value: normal | [ <<length-percentage [0,&infin;]>> | <<flex>> ]+
   		Initial: normal
   		Inherited: no
   		Percentages: refer to length of border-edge side

css-counter-styles-3/Overview.bs

@@ -911,7 +911,7 @@ Zero-Padding and Constant-Width Representations: the 'pad' descriptor</h3>
 	<pre class='descdef'>
 	Name: pad
 	For: @counter-style
-	Value: <<integer>> && <<symbol>>
+	Value: <<integer [0,&infin;]>> && <<symbol>>
 	Initial: 0 ""
 	</pre>
 
@@ -920,7 +920,7 @@ Zero-Padding and Constant-Width Representations: the 'pad' descriptor</h3>
 	Representations larger than the specified pad value are constructed as normal.
 
 	<dl>
-		<dt><<integer>> &amp;&amp; <<symbol>>
+		<dt><<integer [0,&infin;]>> &amp;&amp; <<symbol>>
 		<dd>
 			The <<integer>> specifies a minimum length that all counter representations must reach.
 
@@ -936,8 +936,7 @@ Zero-Padding and Constant-Width Representations: the 'pad' descriptor</h3>
 			If <var>difference</var> is greater than zero,
 			prepend <var>difference</var> copies of the specified <<symbol>> to the representation.
 
-			The <<integer>> must be non-negative.
-			A negative value is a syntax error.
+			Negative <<integer>> values are not allowed.
 
 	</dl>
 
@@ -1030,7 +1029,7 @@ Marker characters: the 'symbols' and 'additive-symbols' descriptors</h3>
 	<pre class='descdef'>
 	Name: additive-symbols
 	For: @counter-style
-	Value: [ <<integer>> &amp;&amp; <<symbol>> ]#
+	Value: [ <<integer [0,&infin;]>> &amp;&amp; <<symbol>> ]#
 	Initial: n/a
 	</pre>
 
@@ -1054,7 +1053,7 @@ Marker characters: the 'symbols' and 'additive-symbols' descriptors</h3>
 	Each entry in the 'symbols' descriptor's value defines a <dfn export>counter symbol</dfn>,
 	which is interpreted differently based on the counter style's system.
 	Each entry in the 'additive-symbols' descriptor's value defines an <dfn export>additive tuple</dfn>,
-	which consists of a <a>counter symbol</a> and a non-negative integer weight.
+	which consists of a <a>counter symbol</a> and an integer weight.
 	Each weight must be a non-negative integer,
 	and the <a>additive tuples</a> must be specified in order of strictly descending weight;
 	otherwise, the declaration is invalid and must be ignored.
@@ -2623,6 +2622,8 @@ Changes since the Jun 2015 Candidate Recommendation</h3>
 	* Specified that invalid values just invalidate the declaration, not the whole rule.
 	* ''@counter-style'' rules that are invalid due to missing descriptors just fail to create a <a>counter style</a>;
 		they're otherwise still valid rules.
+	* Changed syntax to use <a>bracketed range notation</a> to reflect
+		the prose restrictions on negative values.
 
 	A <a href="https://drafts.csswg.org/css-counter-styles-3/issues-cr-20150611">Disposition of Comments</a> is available.
 

css-flexbox-1/Overview.bs

@@ -1647,7 +1647,7 @@ The 'flex' Shorthand</h3>
 	<dl dfn-type=value dfn-for=flex>
 		<dt><dfn><<'flex-grow'>></dfn>
 		<dd>
-			This <<number>> component sets 'flex-grow' <a href="#flex-components">longhand</a>
+			This <<number [0,&infin;]>> component sets 'flex-grow' <a href="#flex-components">longhand</a>
 			and specifies the <dfn dfn>flex grow factor</dfn>,
 			which determines how much the <a>flex item</a> will grow
 			relative to the rest of the <a>flex items</a> in the flex container
@@ -1700,7 +1700,7 @@ The 'flex' Shorthand</h3>
 
 		<dt><dfn><<'flex-shrink'>></dfn>
 		<dd>
-			This <<number>> component sets 'flex-shrink' <a href="#flex-components">longhand</a>
+			This <<number [0,&infin;]>> component sets 'flex-shrink' <a href="#flex-components">longhand</a>
 			and specifies the <dfn dfn>flex shrink factor</dfn>,
 			which determines how much the <a>flex item</a> will shrink
 			relative to the rest of the <a>flex items</a> in the flex container
@@ -1823,9 +1823,9 @@ Basic Values of 'flex'</h4>
 			except that flex items are not allowed to shrink,
 			even in overflow situations.
 
-		<dt>''flex: &lt;positive-number>''
+		<dt>''flex: <<number [1,&infin;]>>''
 		<dd>
-			Equivalent to ''flex: &lt;positive-number> 1 0''.
+			Equivalent to ''flex: <<number [1,&infin;]>> 1 0''.
 			Makes the flex item flexible and sets the <a>flex basis</a> to zero,
 			resulting in an item that receives the specified proportion of the free space in the flex container.
 			If all items in the flex container use this pattern,
@@ -1852,7 +1852,7 @@ The 'flex-grow' property</h4>
 
 	<pre class='propdef'>
 	Name: flex-grow
-	Value: <<number>>
+	Value: <<number [0,&infin;]>>
 	Initial: 0
 	Applies to: <a>flex items</a>
 	Inherited: no
@@ -1867,14 +1867,14 @@ The 'flex-grow' property</h4>
 
 	The 'flex-grow' property sets the <a>flex grow factor</a>
 	to the provided <dfn value for=flex-grow><<number>></dfn>.
-	Negative numbers are invalid.
+	Negative values are not allowed.
 
 <h4 id='flex-shrink-property'>
 The 'flex-shrink' property</h4>
 
 	<pre class='propdef'>
 	Name: flex-shrink
-	Value: <<number>>
+	Value: <<number [0,&infin;]>>
 	Initial: 1
 	Applies to: <a>flex items</a>
 	Inherited: no
@@ -1889,7 +1889,7 @@ The 'flex-shrink' property</h4>
 
 	The 'flex-shrink' property sets the <a>flex shrink factor</a>
 	to the provided <dfn value for=flex-shrink><<number>></dfn>.
-	Negative numbers are invalid.
+	Negative values are not allowed.
 
 <h4 id='flex-basis-property'>
 The 'flex-basis' property</h4>
@@ -3697,9 +3697,13 @@ Boris Zbarsky.
 	This section documents the changes since previous publications.
 
 <h3 id="changes-20181119">
+
 Changes since the <a href="https://www.w3.org/TR/2018/CR-css-flexbox-1-20181119/">19 November 2018 CR</a></h3>
 
 	<ul>
+		<li id="change-2019-bracket-range-notation">
+			Changed syntax to use <a>bracketed range notation</a> to reflect the prose restrictions on negative values.
+
 		<li id="change-2018-used-cross-size">
 			Clarified that the [=flex base size=] calculations
 			rely on the <em>used</em> [=cross size=].