[csswg-drafts] [css-values] Automatic parsing of value definitions

tidoust has just created a new issue for https://github.com/w3c/csswg-drafts:

== [css-values] Automatic parsing of value definitions ==
Context for this issue is that @dontcallmedom and I spent some time integrating CSS specs in the list of specs crawled by [Reffy](https//github.com/tidoust/reffy). Our goal was to extract and parse value definitions for CSS properties and descriptors from all CSS specs, first step that could then perhaps be used to detect potential anomalies, automate the creation of parsing tests, or create tools that list CSS properties (apart from the detection of a few anomalies which led to the issues I reported yesterday and today on individual specs, we haven't had time yet to look into using the result of this parsing).

This exercise was also meant as an occasion for us to take a deeper look at how CSS specs are written. It is quite possible that we misunderstood a few things, we're much more familiar with API specs in practice. Also, as opposed to API specs where the automatic extraction of IDL content allows to create tests, and actual stubs for implementation, the automatic extraction and parsing of value definitions of CSS properties may perhaps not be seen as an interesting goal or a priority, because that does not trigger major interop issues in practice.

That being said, taking for granted that the goal of the [Value Definition Syntax](https://drafts.csswg.org/css-values-4/#value-defs) is to ease the automatic parsing of values, we noted a few potential issues:

1. [Keyword values](https://drafts.csswg.org/css-values-4/#keywords) do not allow for some of the values actually used in specs. The syntax defines keyword values as identifiers which conform to the `<ident-token>` grammar. Unless we read that definition incorrectly, this does not allow keywords to start with a digit or with an `@`. Some values need that such as [`glyph-orientation-vertical`](https://drafts.csswg.org/css-writing-modes-4/#propdef-glyph-orientation-vertical), [`font-weight`](https://drafts.csswg.org/css-fonts-3/#font-weight-prop) (although value was replaced by `<number>` in Level 4), or [`<feature-type>`](https://drafts.csswg.org/css-fonts-4/#font-feature-values-syntax) (e.g. `@stylistic`).

2. The syntax does not describe the use of `=` to define expansion rules of non-terminals. Most specs use `<non-terminal> = <actual-dfn>` equations, but the parsing of that equation is not defined anywhere as far as we can tell. In practice, the `<>` are sometimes omitted on the left-side of the equation as in the [`inset()` definition](https://drafts.csswg.org/css-shapes-1/#funcdef-inset) and [`content-list` definition](https://drafts.csswg.org/css-gcpm-4/#content-list). In other cases, the `=` is not used at all as in the [`fade()` definition](https://drafts.csswg.org/css-overflow-4/#funcdef-text-overflow-fade). Some definitions also use a final semi-colon as in [CSS Display](https://drafts.csswg.org/css-display/#typedef-display-outside), [CSS Box Alignment](https://drafts.csswg.org/css-align/#typedef-content-position) and [CSS Counter Styles](https://drafts.csswg.org/css-counter-styles/#typedef-counter-style).

3. Some specs extend the definition of a property with a "New value" field, which we understand must be combined with the actual definition with a `|` combinator. Unless we missed something, this is not described anywhere though.

4. The syntax talks about quotes, but does not explicitly define which quotes to use. Curly quotes get used in practice in most specs. We were rather reading "single quotes" as meaning the apostrophe `'` character, still used in other specs (such as in CSS 2.2). Anything is fine, but it would be good to make that explicit in the Value Syntax Definition.

5. Some specs mix actual value definitions with prose. I reported the [`fill` property](https://drafts.fxtf.org/fill-stroke/#propdef-fill) in w3c/fxtf-drafts#300 for instance. Another example is the use of dagger characters to reference footnotes in the [`<an+b>` definition](https://drafts.csswg.org/css-syntax-3/#the-anb-type). These values are not ambiguous for human beings, but makes automated parsing more challenging.

6. From time to time, some rules that could be defined with an `=` construct are actually defined in prose. For instance, [`<basic-shape>`](https://drafts.csswg.org/css-shapes/#typedef-basic-shape) could perhaps be defined as `<inset()> | <circle()> | <ellipse()> | <polygon()>`, or [`<border-style>`](https://drafts.csswg.org/css2/box.html#value-def-border-style) as `none | hidden | dotted | dashed | solid | double | groove | ridge | inset | outset`. The generic question is whether that is something that you'd like to encourage.

7. The syntax does not allow to define apparently "simple" things such as ranges or regular expressions. We noted the discussion in w3c/csswg-drafts#355, so that's probably under way.

All in all, what we're wondering is whether it could be useful to end up with a CSS Value Definition Syntax that would allow the creation of a dump similar to the IDL index that appear at the end of API specs. For instance, for [CSS Display Module Level 3](https://drafts.csswg.org/css-display/), this dump could be:
```
display = [ <display-outside> || <display-inside> ] | <display-listitem> | <display-internal> | <display-box> | <display-legacy>

<display-outside> = block | inline | run-in
<display-inside> = flow | flow-root | table | flex | grid | ruby
<display-listitem> = <display-outside>? && [ flow | flow-root ]? && list-item
<display-internal> = table-row-group | table-header-group | table-footer-group | table-row | table-cell | table-column-group | table-column | table-caption | ruby-base | ruby-text | ruby-base-container | ruby-text-container
<display-box> = contents | none
<display-legacy> = inline-block | inline-table | inline-flex | inline-grid
```

CSS Flexbox would then complete the definition of `display` with:
```
display |= flex | inline-flex
```

Please view or discuss this issue at https://github.com/w3c/csswg-drafts/issues/2921 using your GitHub account

Received on Friday, 13 July 2018 09:59:17 UTC