Additional spec metadata

[bkardell]

Most modern specs include additional metadata near the head that link to issue tracking, tests, mailing list or whatever - (see for example https://www.w3.org/TR/css-grid-1/). Generally speaking I find this incredibly helpful as links are right there in context and don't require me to find one of many bookmarks or notes somewhere else to try to remember where to file an issue - I just have to remember how to get to the spec. This seems like a pretty easy add and if we want to encourage wider participation it feels like this would be a really helpful addition.

[fred-wang]

From https://lists.w3.org/Archives/Public/public-mathml4/2019May/0006.html

We agreed to add something, at least a link to "test-needed". @davidcarlisle was not present during that meeting, we were waiting for his feedback about this.

[davidcarlisle]

On Thu, 16 May 2019 at 08:45, Frédéric Wang ***@***.***> wrote: From https://lists.w3.org/Archives/Public/public-mathml4/2019May/0006.html We agreed to add something, at least a link to "test-needed". @davidcarlisle <https://github.com/davidcarlisle> was not present during that meeting, we were waiting for his feedback about this. Yes sorry about that: had family stuff to sort out, I'll try to catch up

on spec issues this weekend.

[fred-wang]

@bkardell Do you know which tools other groups (e.g. CSS WG) use to generate their spec and metadata?

[bkardell]

yes, bikeshed and respec both do this for you - @davidcarlisle and I discussed this.

[davidcarlisle]

as I just said on the call I have no issue with you switching to respec or whetever if you want, on the other hand adding WPT links in the document and any other fixed links in the document head in the current setup wouldn't be hard if you want me to do that still, but no point extending the current build system if you think you will switch.

[bkardell]

As I am not an editor, as I said, this is the less important point to me (which thing we use), so I am happy with whatever the editors are happy with.

[fred-wang]

I don't really have preference as an editor. Moving to an existing framework used by other WG will probably be a bit more effort in the short term just get these metadata added but it will be less maintenance burden in the long term than a custom solution.

[fred-wang]

@bkardell @davidcarlisle I started migration to respec: https://mathml-refresh.github.io/mathml-core/
There are a few things to fix (especially rewrite generation of operator tables) but that seems to work pretty well.

[davidcarlisle]

@fred-wang yes looks fine, seems like you should be able to adjust the operator dictionary section to use respec data-include attribute to include a suitable table. If you/we just modify the existing html by hand to make an op-dict.html that includes well, I can adjust the existing extraction from unicode.xml to do whatever is needed. The data shouldn't change that often so I don't think we need to make it regenerate every time, just treat an html operator dictionary as source as far as respec is concerned?

[fred-wang]

@davidcarlisle yes, I guess we can do like for the figures: Just provide some script to generate the operator dictionary table in HTML format. Then use data-include or similar to include the HTML content. Same for the combining op table.

[davidcarlisle]

@fred-wang I can do that later today if you want, but if you want to do it now feel free.

[bkardell]

I love it already :)

[davidcarlisle]

I checked in html fragments for the combining character and operator dictionary tables, and arranged respec to include them.

I put the xsl to generate these in the figures directory so it isn't lost, but it does not need to be run unless we change the data.

As before I linked to sorttable.js to make the operator dictionary sortable on the various columns, this doesn't work, possibly timing conflict with respec, but I didn't investigate further just now. Not sure that's the best table sorter these days anyway (It is simple and has worked well enough in the mathml spec for years but I am open to suggestions), formatting of all the tables probably needs adjusting but at least the basic data is now in respec compatible form....

[fred-wang]

@davidcarlisle Thanks. I suspect we'll need to add the sortable stuff in the postProcess: https://github.com/w3c/respec/wiki/postProcess

[fred-wang]

@bkardell @davidcarlisle I rewrote all the linking stuff for sections, figures, issues, references etc. I also relied on definitions for elements, attributes and attribute values. Tomorrow I'll try to experiment with the WPT references.

[fred-wang]

The spec now has a lot of metadata:
https://mathml-refresh.github.io/mathml-core/

Maybe the only thing missing is examples (but maybe that's not really spec)

We could also add some JS to retrieve the result of https://build-chromium.igalia.com/mathml/wpt/summary.html (from https://build-chromium.igalia.com/mathml/wpt/blink-latest.json etc) to add browser scores similar to bikeshed.

[fred-wang]

Opened #137

I think we can close this.