caniuse integration

[cvrebert]

Would you be open to a PR to add caniuse browser support data boxes, like the HTML spec has?

X-Ref: whatwg/dom#69

[tabatkins]

Yeah, I'm down with this. I'd put it behind a pref by default, and we should talk about design, but I'd def love to see this integrated.

[cvrebert]

I'd put it behind a pref by default

Sure, makes sense. Could you point me to an existing pref I could use as a reference when writing the new code?

[tabatkins]

The pref for dfn-panels is pretty canonical for this sort of thing: https://github.com/tabatkins/bikeshed/blob/master/bikeshed/MetadataManager.py#L115 (and lines 78 and 173)

[cvrebert]

As far as appearance, any qualms with presenting the data roughly the same way the HTML spec does?
Example: https://html.spec.whatwg.org/#attr-style-scoped

[cvrebert]

Would adding a pref for the spec's public URL (e.g. Public URL: https://dom.spec.whatwg.org) be okay? Need this in order to determine which caniuse entries are relevant. Feel free to suggest a better name.

[tabatkins]

As far as appearance, any qualms with presenting the data roughly the same way the HTML spec does?

Yeah, the HTML spec's presentation works for me. We're already copying WHATWG's default styling for dfn-panels. ^_^

Would adding a pref for the spec's public URL

We can definitely add whatever additional metadata we need, but I don't think that spec url is useful here. CanIUse's data (from the db) appears to group features pretty arbitrarily.

Looking into how CanIUse actually groups things now, I think I see two potential design avenues:

Baked into the spec (all done in Python)

1. We add an update step that fetches and parses the caniuse data, so Bikeshed can run purely locally. This is easy, just fetch all the files and concat them into a JSON structure keyed by the contents of each object's "title" property, lowercased.
2. No additional metadata needed.
3. An individual dfn-capable element can have a caniuse attribute, whose value is lowercased and looked up in the data file. If match, we output the caniuse panel; if no match, fatal error.
4. The caniuse panel should be a child of the heading/dfn, same as dfn-blocks are, so we can rely on abspos static positioning to figure out where it should go horizontally. It needs a data-deco boolean attribute added to it so it'll be ignored by dfn-parsing spiders, and a caniuse-paneled class added to the dfn/heading (for styling purposes)
5. Remove the caniuse attribute from the output in the cleanup step.

Pros:

• Panels show up immediately when you load the spec, no load time.
• Not dependent on any external server being up.
• Can do error-checking (like verifying the key actually exists) at build time.

Cons:

• Data might be stale, if the spec was last generated a long time ago or the generator hasn't updated their data files recently. Probably need to include the data's date in each panel as a small disclaimer, "as of Mar 2016" or similar.

Done Dynamically in JS

1. Still no metadata needed.
2. Gate including the script on the presence of a data-caniuse attribute on at least one dfn-capable element. Allow it to be written as just caniuse in source, and canonicalize it to data-caniuse.
3. Script does similar things to what I said above, but fetches data over XHR. If key doesn't exist, console.error() it.

Pros and cons are exactly the opposite of the Python solution: data is up-to-date, but panels aren't visible immediately, they depend on the caniuse-db site being available, and error-checks don't happen until people view the spec.

[cvrebert]

CanIUse's data (from the db) appears to group features pretty arbitrarily.

How so?

Baked into the spec (all done in Python)

This is the route I'm currently pursuing.

1. We add an update step that fetches and parses the caniuse data, so Bikeshed can run purely locally. This is easy, just fetch all the files and concat them into a JSON structure keyed by the contents of each object's "title" property, lowercased.

Even simpler: Just download https://raw.githubusercontent.com/Fyrd/caniuse/master/fulldata-json/data-2.0.json in the update step and store it locally.

We can definitely add whatever additional metadata we need, but I don't think that spec url is useful here.
[...]
An individual dfn-capable element can have a caniuse attribute, whose value is lowercased and looked up in the data file.

That seems like unnecessary extra work for the spec writer.
My current approach is to automatically map caniuse's spec URLs (e.g. https://dom.spec.whatwg.org/#dom-element-classlist for http://caniuse.com/#feat=classlist ) back to the relevant element (#dom-element-classlist). Hence why I need the public URL; I need to be able to determine whether a feature's spec URL refers to the spec currently being processed.

[tabatkins]

Even simpler: Just download https://raw.githubusercontent.com/Fyrd/caniuse/master/fulldata-json/data-2.0.json in the updatIe step and store it locally.

Ah, didn't see he had an "all data" file; that's exactly what I was suggesting we build. ^_^

My current approach is to automatically map caniuse's spec URLs (e.g. https://dom.spec.whatwg.org/#dom-element-classlist for http://caniuse.com/#feat=classlist ) back to the relevant element (#dom-element-classlist).

This doesn't work, is my point. For example, background-attachment is associated with the url http://www.w3.org/TR/css3-background/#the-background-attachment. This (a) is the TR url, which feels weird to force EDs to refer to, especially if you're writing the ED for the next level, (b) assumes that specs don't split/rename or move properties around, such that they're composed of bits from multiple spec urls in the caniuse db, and (c) requires any specs that want this data to have the exact same anchor as the "official" version that caniuse stores (and assumes that the anchor caniuse chose is the anchor the spec author wants to attach the usage data to).

What I suggested is a little bit more work, and less "magic", but it's dependable, as long as caniuse doesn't change their keys. I've gradually learned that depending on URL structures is generally gonna be a bad time. ^_^