[css-align] Values section shouldn't point wholesale to CSS Level 2

[dbaron]

The Values section of css-align currently says:

This specification follows the CSS property definition conventions from [CSS2]. Value types not defined in this specification are defined in CSS Level 2 Revision 1 [CSS2].

I think the section this points to has become sufficiently out-of-date by this point that it's probably best to point mostly to the relevant level 3 modules rather than level 2. Most drafts don't have a section like this one, and I don't think such a section would be needed if bikeshed implemented speced/bikeshed#617

[fantasai]

I think for people reading in a non-interactive format (like print), having this statement in addition to the bikeshed links would be useful. That said, updating the boilerplate is probably a good idea; as is making sure it is consistently applied across all of our specs. This Values section is part of our module template.

[tabatkins]

On the other hand, these Values sections are usually straight boilerplate, copypasted from other specs without really looking, and then left to rot. This spec's Values section shows that off in spades - it has a weird separate treatment of "initial" and "inherit", and doesn't mention the other global values. It should instead just talk about global values and point to Cascade.

We should figure out how to work this into our actual boilerplate so people wont' have to worry about it.

[fantasai]

Proposed replacement:

This specification follows the <a href="https://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]].
Value types not defined in this specification are defined in CSS Values & Units [[!CSS-VALUES-3]].
Other CSS modules may expand the definitions of these value types.

In addition to the property-specific values listed in their definitions,
all properties defined in this specification
also accept the <a>CSS-wide keywords</a> keywords as their property value.
For readability they have not been repeated explicitly.

[fantasai]

Agenda+ to get review on updating across all specs.

[tabatkins]

Which is to say: I updated all the specs that had a Values section to match this wording; I'm happy to do further updates if the WG wants a different boilerplate.

(There's only 21 specs with a Values section:

• css-align
• css-animations
• css-backgrounds
• css-break
• css-display
• css-line-grid
• css-position
• css-ruby
• css-scroll-snap
• css-shapes
• css-size-adjust
• css-sizing-3
• css-sizing
• css-speech
• css-text-decor-4
• css-text-decor
• css-text
• css-transforms-2
• css-transforms
• css-writing-modes-3
• css-writing-modes

)

[svgeesus]

There's only 21 specs with a Values section:

Does that mean the others don't need one, or just that they don't have one (and should)? I'm finding it difficult to think of a CSS spec (except for Selectors and Namespaces) which won't use values.

[tabatkins]

Mostly "don't have one, but could possibly use one". Tho my position is stated in an earlier comment - this is boilerplate, and should be put in the boilerplate section somehow.

(If I can copy-paste the exact same text between 21 specs, and theoretically another 20 or so, then it's not something that should be hand-written into specs.)

[css-meeting-bot]

The CSS Working Group just discussed [css-align] Values section shouldn't point wholesale to CSS Level 2, and agreed to the following resolutions:

• RESOLVED: New Values boilerplate accepted

The full IRC log of that discussion

<astearns> topic: [css-align] Values section shouldn't point wholesale to CSS Level 2
<gregwhitworth> TabAtkins: can you submit a test for this when you make the change?
<astearns> github topic: https://github.com//issues/1397#issuecomment-311471628
<fantasai> TabAtkins: Issue raised by dbaron on css-align, the values section pointed straight to CSS2
<fantasai> TabAtkins: better to point to more up-to-date specs
<fantasai> TabAtkins: This text shows up in many of our specs, so we went an updated all of them... we can revert or change as necessary
<TabAtkins> https://github.com//issues/1397#issuecomment-311471628
<fantasai> TabAtkins: Because it's a wide-ranging change, wanted to get WG approval before making part of spec boilerplate
<fantasai> This specification follows the <a href="https://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition conventions</a> from [[!CSS2]].
<fantasai> Value types not defined in this specification are defined in CSS Values & Units [[!CSS-VALUES-3]].
<fantasai> Other CSS modules may expand the definitions of these value types.
<fantasai> In addition to the property-specific values listed in their definitions,
<fantasai> all properties defined in this specification
<fantasai> also accept the <a>CSS-wide keywords</a> keywords as their property value.
<fantasai> For readability they have not been repeated explicitly.
<fantasai> Florian: Seems to work for vast majority of specs. Have you checked it makes sense for specs that don't define properties?
<fantasai> Florian: Like MQ or Selectors?
<fantasai> TabAtkins: Those either don't have values section or it worked.
<fantasai> TabAtkins: One or two specs had an extra line of text, but everything that had a value section could take this without any addition
<fantasai> Florian: If put in bikeshed boilerplate?
<fantasai> TabAtkins: Defer that question to later
<fantasai> TabAtkins: Just wanted to verify the text, and if ppl ok to me updating all the specs
<fantasai> dbaron: I'm okay with the replacement, but think it could use further improvement.
<fantasai> dbaron: E.g. in Animations we define Animation line, CSSOM defines another line...
<fantasai> fantasai: I think we should have an updated propdef explainer somewhere, e.g. snapshot
<fantasai> dbaron: can just make everything hyperlinked
<fantasai> fantasai: Yeah, but should have more explanation than just a hyperlink
<fantasai> ...
<fantasai> Florian: ???
<fantasai> TabAtkins: It was definitely outdated, e.g. didn't link to CSS-wide keywords becaus that wasn't a thing
<fantasai> TabAtkins: Definitely better than what we have, could improve further.
<Florian> s/???/did any of the sections to be replaced have anything about what dbaron mentioned? if not, it's a strict improvement and we can deal with that later/
<fantasai> astearns: So you want approval of the changes
<fantasai> fantasai, Tab: Yes
<fantasai> fantasai: And also if there are specific changes desired, resolve to have us propagae those or discuss further in GitHub
<fantasai> astearns: Proposed to accept this improvement, raise GitHub issues for further improvement
<fantasai> RESOLVED: New Values boilerplate accepted