What's the "current version" of a spec, for CSS reference docs?

[wbamberg]

This came out of mdn/content#28900, which has come up before, although I can't find the other one now.

The CSSSyntax macro uses @webref/css to display formal syntax for CSS properties. In this algorithm, we find all specs in webref that include a property, and exclude any specs that only differ by their numeric suffix. Then we use the remaining specs to find values to show in the formal syntax.

For example, if we are looking for font-size-adjust, we find 2 entries in webref, "css-fonts" and "css-fonts-5". We discard "css-fonts-5" and just use "css-fonts" - that is, we consider "css-fonts" as the "current version" of the spec. This algorithm came out of the discussion mdn/yari#4656 (comment) and subsequent comments.

In this case that means excluding the extra values that are added in level 5, namely [ ex-height | cap-height | ch-width | ic-width | ic-height ].

But BCD lists "css-fonts-5" as the current spec, meaning that if people look at the linked spec, there's a discrepancy.

What should we do here? It seems to me:

• that BCD and formal syntax should agree on what's the current spec. I'm not sure who's right here, but the discussion in feat(macros): rewrite CSSSyntax macro yari#4656 (comment) leads me to believe that CSSSyntax is right.
• ideally, we should only represent "the current spec" in one place (so for example, formal syntax should use the spec in BCD to find values). But this isn't possible because BCD sometimes uses multiple URLs for an item, and there are no clear rules about that.

A further issue here is that the "Values" section is also out of step with the others sometimes. This section is entirely manually maintained, and even the exact nature of what kind of thing it contains isn't always very clear. We could imagine a future in which the allowed set of items in "Values" is driven by webref as well, and we then have consistency across all these parts of the page.

[OnkarRuikar]

Do we update these pages as soon as a new version of the spec lands, some browser implements it, or someone creates an issue\PR on GitHub?

What's the "current version" of a spec, for CSS reference docs?

The GitHub issue is complaining about the description on the page doesn't match the syntax. So logically the syntax should match whatever is documented on the page irrespective of the "current" or "the latest" versions. When the syntax doesn't match, the syntax section is not useful to the reader because there is no explanation for extra(new) values or creates doubts about missing(old) values.
If syntax starts/stops changing due to external forces then the documentation(not just values section) on the pages won't remain whole(consistent). The author who is updating the content should have access/ability to update syntax section as well.

... formal syntax should use the spec in BCD to find values ...

+1 Current workflow is to create a PR in content repo and at the same time create a PR in BCD repo. This keeps content and compatibility in sync. Having syntax hint/URL in BCD will easily keep syntax in sync as well.

But this isn't possible because BCD sometimes uses multiple URLs for an item, and there are no clear rules about that.

We can have a new optional field syntax-ref which will point to the spec URL that we want to use for syntax. If not BCD then we can have the optional field in content front-matter. This will be used only in special cases where conflict arises.

Or the version or spec location that the author wants to use can be passed to the macro call. This will keep the syntax bound to the surrounding content.

---

A further issue here is that the "Values" section is also out of step with the others sometimes.

For now we can have a tool and nightly/weekly workflow to check Values section using webref/css. We can check for number and structure of values against the latest available syntax. And flag mismatches as a GitHub issue.

[Rumyra]

Thanks for considering this @wbamberg - initially I was wondering whether a bcd or webref solution would fit, so we don't have to hand curate further data which in my ideal world would be automated :)

However I really like @OnkarRuikar 's solution here

We can have a new optional field syntax-ref which will point to the spec URL that we want to use for syntax. If not BCD then we can have the optional field in content front-matter. This will be used only in special cases where conflict arises.

Whilst I'm also against adding too much to frontmatter incase it gets overly complicated, this seems like a nice solution, used as an override essentially

[wbamberg]

This will be used only in special cases where conflict arises.

What is "conflict" and how do we know when it happens? What's our actual desired policy wrt CSS spec versions: that is, which version should we document? I mean at the moment there is "conflict" between CSSSyntax and BCD for font-size-adjust, because BCD chooses css-fonts-5 and CSSSyntax chooses css-fonts-4 (which is the "current specification"). What do we want to appear in the page in a case like this?

(It feels like, in this case at least, we probably want css-fonts-5, since it includes values which are shipping in browsers, so which we want to talk about. But does that mean we should always try to choose the very latest level, and what might go wrong if we do?.)

Or does "conflict" only mean: cases where there is more than one spec-url entry in BCD? Daniel had an interesting comment on this: mdn/yari#4656 (comment). I think the situation has changed a bit here in the last few months, given mdn/browser-compat-data#13804, but in the cases Daniel lists where there is more than one spec URL entry in BCD, what policy gives rise to these choices?

For instance, https://developer.mozilla.org/en-US/docs/Web/CSS/font-family#specifications has 2 entries, one to https://drafts.csswg.org/css-fonts/#generic-font-families and one to https://drafts.csswg.org/css-fonts/#font-family-prop. What's the reasoning for the first of these?

ISTM that without knowing the answers to these policy choices, it's not really possible to know when a spec URL is correct or not.

[wbamberg]

To go further, adding another front matter key for this feels like a hack to work around the fact that sometimes the BCD spec_url doesn't seem to be useful.

[hamishwillee]

(It feels like, in this case at least, we probably want css-fonts-5, since it includes values which are shipping in browsers, so which we want to talk about. But does that mean we should always try to choose the very latest level, and what might go wrong if we do?.)

IMO the spec that reflects what is "shipping in browsers" is the right one to generate a formal syntax from. The cost is that the formal syntax generated from this will have more items that actually aren't in browsers - would be good to be able to exclude items that aren't anywhere or at least have a note that this is generated and might not reflect browsers.

I guess multiple specs might be needed because in some cases the functionality in browsers reflects older spec behaviour. In WebAPI you need multiple specs because extensions and particular implementations of frameworks can appear in their own docs - perhaps CSS is similarly iterative?

FWIW I am not opposed to the idea that docs might override BCD, but like Will I'm inclined to think that this not really a conflict that needs to exist. I might be missing something.

[wbamberg]

IMO the spec that reflects what is "shipping in browsers" is the right one to generate a formal syntax from.

Yeah, I think you are right.

The cost is that the formal syntax generated from this will have more items that actually aren't in browsers

Yes, I think if we change the csssyntax policy to use more bleeding edge specs this is a question we'd have to look into. In general though I think it is OK for formal syntax to list things that aren't supported: it's BCD's job to tell that story.

I guess multiple specs might be needed because in some cases the functionality in browsers reflects older spec behaviour. In WebAPI you need multiple specs because extensions and particular implementations of frameworks can appear in their own docs - perhaps CSS is similarly iterative?

Sometimes a CSS property is defined across multiple different specs (rather than multiple versions of the same spec).

The way these appear in webref/css is that one spec has the syntax for the property in its value key, and the other specs define additional values in a newValues key, and csssyntax handles this by concatenating newValues onto values.

So for example, column-width has a base definition in the Multi-column layout spec, then gets extra values defined in the Box sizing spec, and csssyntax lists the complete syntax.

This might seem like a legitimate case for BCD to list multiple specs? In these cases, sometimes BCD does list multiple specs (column-width), but sometimes it doesn't (position). Again: is there a reason for this discrepancy? What is BCD's policy for handling cases like this?

Would it be practical to use webref to get spec URLs, instead of BCD? (I mean for the spec table too, not just the formal syntax).

[hamishwillee]

Thank you. I'm not sure what I can add to the discussion, but here are a few thoughts with ^^^^ in mind:

As a user

• I want to know what is available in actual browsers: a spec link that omits that information would frustrate me.
• I don't mind if the spec includes things that aren't implemented - I'm only there for detail checking: I rely on MDN for the high level and knowing what is supported.
• On the MDN page I really prefer only see what is implemented in browsers. For the syntax:
  • I think it is preferable if this does not contain things that aren't supported in browsers, but it is better that it contains extra than it omits supported stuff.
  • A note that formal syntax reflects a spec rather than browser content in an information bubble might help here.
  • I quite like the idea of being able to show multiple versions of the spec and let people choose their version. But I think that what gets displayed as the first thing a users sees should be the latest spec that covers the option.
  • Following on from that, if something is only in a delta spec, I think the delta spec should be what is displayed "first".

BCD is about compatibility, but you're still trying to provide links to all the relevant specs. It doesn't make sense to me that you'd choose the last full spec if any of the contained entities are not in that spec (are in a delta spec) - you'd have to have both. If the entities in the feature cross different specs, then you'd need those in whatever spec versions are covered too.

I guess you could decide to somewhat automate this - specify last full spec for feature level, and auto-add any delta specs to the feature level if they are what is referenced in a sub feature.

[wbamberg]

Right, our practice on MDN is to document what is shipping in browsers, not what is written in specs. But since formal syntax is derived only from the specs, we get a mismatch. When part of a spec is shipping and part is not, we get a mismatch which can't be resolved just by choosing a particular spec version. For example, for text-overflow we document one of the values from the delta spec (<string>) but not the others (fade and fade()), because (AFAIK) of these new values, only <string> is supported.

If we include only the full spec syntax we omit <string>, and if we include the delta syntax we include fade and fade().

I think it is preferable if this does not contain things that aren't supported in browsers, but it is better that it contains extra than it omits supported stuff.

The problem with that is that as a reader you don't know that fade and fade() are not implemented, because BCD never tells you when things are not implemented, but only when they are implemented.

As you say, maybe a note that "this syntax reflects the specification: not all values listed here may be supported in browsers" but it's a bit sad when we can't tell them which values are not supported.

One alternative would be to figure out in which cases support for properties is incomplete, and have a manually-curated override for webref/css for those cases. It feels like a step backwards but it would be better for users.

[OnkarRuikar]

As you say, maybe a note that "this syntax reflects the specification: not all values listed here may be supported in browsers" but it's a bit sad when we can't tell them which values are not supported.

👍 This is the easiest solution. We display the latest spec syntax and mention in a note at the top or bottom in fine print that "This syntax is from the latest specs. Some features may not be available in browsers yet."

If we put a bit more effort then in yari we can put greenish background for features available in BCD and reddish background behind the ones not available in BCD.

One alternative would be to figure out in which cases support for properties is incomplete, and have a manually-curated override for webref/css for those cases. It feels like a step backwards but it would be better for users.

This is a lot of work and may not be feasible unless put under a separate project. We need to generate all the syntaxes from webref/css and correct them one by one and put inside a separate repo. And whenever a new webref/css release is made we compare current snapshot with the latest one and update the repo...

[wbamberg]

👍 This is the easiest solution. We display the latest spec syntax and mention in a note at the top or bottom in fine print that "This syntax is from the latest specs. Some features may not be available in browsers yet."

Yes, it is easy, but telling people that some values might not be supported, without telling them which ones these are, is not very helpful. It's surely a reasonable expectation for a web docs site to be able to tell people things like this, and not just say "it's too hard to work it out".

[hamishwillee]

👍 This is the easiest solution. We display the latest spec syntax and mention in a note at the top or bottom in fine print that "This syntax is from the latest specs. Some features may not be available in browsers yet."

Yes, it is easy, but telling people that some values might not be supported, without telling them which ones these are, is not very helpful. It's surely a reasonable expectation for a web docs site to be able to tell people things like this, and not just say "it's too hard to work it out".

@wbamberg It removes the "presumption of accuracy", and while that's not perfect, but it is significantly better than what we have now.

Partially I like this because I am a cynic - getting any of the other suggestions accepted in a reasonable timeframe seems pretty hard/unlikely.

[OnkarRuikar]

But doing this in a blanket way makes me a bit nervous, given the scary warning on, say, drafts.csswg.org/css-backgrounds-4/#background-clip.

There is always going to be some odd cases. We need to have some override mechanism for special cases. Can we have an optional parameter to the macro {{CSSSyntax("css-font-5")}}?
The argument value will be one of the options offered by webref/css API (or we can have a simple API in query-css-syntax which will return available options for a feature).

I wonder whether we could: always use unnumbered versions in BCD

In this case are we going to downgrade the document to match css-font-4?
Why not always use the latest version and for odd cases have {{CSSSyntax("css-backgrounds-3")}}

[wbamberg]

This is implementation - "how do we do it" while I think we are still in requirements "what do we want to do". Sure, adding a new argument to CSSSyntax is easy. What's hard is figuring out what we want to do, across all the CSS properties: that is, what kinds of policies are going to be best for readers. Once we know that, we can talk about how to implement it, and maybe we'll be able to implement it with the tools we already have rather than inventing new ones.

Having bits of machinery without clear rules for how they are to be used is a recipe for confusion.

There is always going to be some odd cases. We need to have some override mechanism for special cases.

It's hard for me to imagine a case where we want to show one version in "Values" and "Specifications" and "Browser compatibility", but a different version in "Formal syntax". Won't that always be confusing? Do you know of such a case?

[OnkarRuikar]

There is always going to be some odd cases. We need to have some override mechanism for special cases.

It's hard for me to imagine a case where we want to show one version in "Values" and "Specifications" and "Browser compatibility", but a different version in "Formal syntax". Won't that always be confusing? Do you know of such a case?

Here, I meant the case where we documented future version(say v5) on the page but CSSSyntax returns (v4 or current). As webref provides syntax for each doc version we should be able to choose v5 so that the syntax matches "Values" and BCD table.

[wbamberg]

I wonder whether we could: always use unnumbered versions in BCD

In this case are we going to downgrade the document to match css-font-4?

No. We can list the unnumbered version in BCD, because as Florian says this is evergreen: it won't go stale as new spec versions ship. But we can use browser-specs to find, from the unnumbered version, both the current full version and the latest delta.

[yarusome]

How about this: For any CSS property/type/etc.,

1. require that if any spec in BCD is numbered without a corresponding unnumbered spec, this numbered spec must have a value entry;
2. concatenate the value and newValue entries from the specs in BCD.

Listing syntaxes from latest specs also requires that BCD not only lists what has been implemented, but also what has not been yet. This requirement should better be emphasized in BCD's contributing guide, in my opinion.

---

For staleness of the "Values" section, I'm thinking about this procedure:

1. On a monthly/quarterly basis, fetching the latest return values of {{CSSSyntax}} for all CSS reference pages that call this macro.
2. Comparing the latest values to the cached values from last month/quarter.
3. If there is any difference, make a bot open a task issue in mdn/content to list staled pages.
4. Cache the latest values.

An issue is that literal comparison of {{CSSSyntax}}, even if the macro does some normalization so that linting-only changes from specs are invisible, might cause some false positives. For example, a spec changes the production of some non-terminals that results in identical fully-expanded syntaxes. But I doubt if such false positives would be of a considerable proportion.

[yarusome]

This is indeed simpler to implement, but it is incompatible with mdn/content#28953, where paramters are represented in without angles and might bear names different from those in specs.

[wbamberg]

Listing syntaxes from latest specs also requires that BCD not only lists what has been implemented, but also what has not been yet. This requirement should better be emphasized in BCD's contributing guide, in my opinion.

I expect it would be difficult to get consensus for this in BCD. But I could be wrong.

[teoli2003]

What is missing in BCD is a clear definition, for each feature, of what "Basic support" means. With that, you can deduce what is not supported without introducing all proposals into BCD.

We could think about what information should be there to filter the formal syntax from webref (in most cases).

[wbamberg]

Oh yes, I'd forgotten about basic support. Can we find a generic way to do this? Could basic support link to a spec URL, and mean "support for the feature as defined in this version of the spec"? Can that be generalized across not just CSS but other domains? It sounds like that might be tricky.

[teoli2003]

I think the trickiest case is CSS, where syntax can be complex. For API, and JS, we list all supported members in BCD, and for these only parameters, values and special changes that we don't care here can changes. Similar for HTML/SVG/MathML elements, though the parameter list is not necessary complex.

Only CSS is really complex here.

[Rumyra]

I gave this another re-read today and am collating my thoughts moving forward. I jumped on the bcd call today to get a feel of thoughts there as well as that seems to be quite integrated into this discussion - for instance:

I expect it would be difficult to get consensus for this in BCD. But I could be wrong.

Maybe not? But I would ask how high we think the priority is for solving the issue as it stands at the moment, which is discrepancies on pages. Do we want a short term solution, while we consider a more robust longer term one which (probably) involves influencing bcd?

[OnkarRuikar]

Do we want a short term solution, while we consider a more robust longer term one which (probably) involves influencing bcd?

Should we remove/hide the Formal syntax section till we are able to provide the accurate data or address this completely?
People have been raising issues in the content repo saying the formal syntax is wrong/incomplete. Eventually the section will get bad reputation and people will start ignoring it naturally.