Source format for MathML4 (full)

[davidcarlisle]

The sources for MathML4 are in a (version of) xmlspec xml markup (similar to that used by xml spec itself and the xslt/xquery set of specifications and perhaps others of a similar age).

The XSLT based toolchain is very flexible but really as it is highly customised it takes some care to setup and maintain, especially as W3C spec requirements change over time so the target format needs to be adapted.

Personally I prefer the XML pipeline to (say) the html+JavaScript respec pipeline but the experiment to switch mathml-core to respec has been largely successful and I do not have the time really required to maintain the current build and (probably more importantly) I fear for the long term maintenance of the mathml spec if kept in this form.

I have experimented with a fork in my github area using respec for the full spec

https://davidcarlisle.github.io/mathml/

This has just been done this afternoon and is not complete (still some respec errors and not all features fully converted) However:

• It seems to basically work
• The html sources do not look so much harder to work with than the original xml.
• The build process is a lot simpler (just view the file, no need for travis to build the spec and commit updates in the background).

It should be noted that this version (perhaps permanently) lacks some of the multi-format aspects of previous builds

• Single file html (5) version only (mathml to be added later)
• No split-on-chapter mulri-file html4 version
• No diff marked version (respec has its own html diff mechanisms, so a different diff marked version could be constructed later)
• No PDF version
• No Index appendix listing use of mathml elements (could in theory be re-implemented in JavaScript, but not today)

If the Group decides to go with this idea the fork could trivially be merged back into mathml-refresh/mathml and then deleted.

[NSoiffer]

Seems like an issue is examples -- showing what the MathML should look like. In the past, the multiple versions allowed showing an image and also showing the result of the browser rendering. When I skimmed through https://davidcarlisle.github.io/mathml/, I didn't see any images or displayed MathML at all.

Seems like we need a plan for this. We could use MathJax to render the math, but MathJax doesn't implement all of MathML. Also, if it is rendered as a single page, I suspect adding MathJax would really slow it down, even if it were done by chapters, at least for the presentation and content MathML chapters which have (or had) lots of examples.

[davidcarlisle]

@NSoiffer yes danger of putting up initial drafts however I wanted to flag this as a possible direction before spending too long implementing things in respec, currently it is just the result of a quick translation of the xml to html and minimal respec setup.

The example images should be there (that is the <img elements are there in the publised html, just all the links to the images are broken, I clearly did something stupid with github-pages or respec setup, will fix later.

For mathml rendering I don't think we should use mathjax, you can see how that would look by choosing the mathjax option in the mathml3 spec here

https://www.w3.org/TR/MathML3/mathml.html

However I think that sends the wrong signal.

My suggestion would be that replacing the two javascript options as in mathml3 we just have one, which exposes a content to presentation translation + mathml-core rendering, or perhaps have no user option at all and by default use mathml-core rendering and if you detect in javascript that that isn't working then you simply show things as now (with no mathml rendering)

[davidcarlisle]

The images should be back now.

[fred-wang]

I think it's still possible to keep part of the XML pipeline and combine it with respec if needed.

One of the issue with respec is that generating everything can take a few seconds. Another issue is that references are sometimes broken, maybe because of a network issue. The respec doc indicates a (non-automated way) to create snapshot:
https://github.com/w3c/respec/wiki/ReSpec-Editor's-Guide#creating-a-static-snapshot

The respec doc also indicates how to generat epub/pdf (again in a non-automated way):
https://github.com/w3c/respec/wiki/ReSpec-Editor's-Guide#editors-drafts

Regarding the examples, IIUC the goal is to make the text of the spec more understandable. It seems wrong to me to use them as an integrated mathjax/browser "test suite" or as normative reference rendering. Also, we agreed that the spec shouldn't depend on external polyfill like MathJax or on native MathML rendering. Finally, MathJax does not even use MathML spacing by default, does not implement MATH support and does not have the compatibility with HTML5 technology requested by the core spec. So:

• I'm happy if we keep only the HTML5 version for the spec, maybe with links to an external repo containing MathML examples / tests / demos (note: working with a reduced testcase file is easier, so it makes sense to have separate file for each example)
• I believe the examples should all be wrapped in class="example" div to make clear they are not normative.
• I would use images for sample rendering, relying on native rendering when possible.

I plan to add/import examples to the core spec too.

[davidcarlisle]

Yes we can keep parts as needed (eg for processing unicode.xml ) and at present the "respec sources" are generated by xslt from the original xml, until I am sure I have captured all the details (eg need to add more markup around the examples as you note) But I think that if the sources are just html files it will be easier to get people to edit so I think for the main part of the document respec may work out OK even though it has its quirks... So if we go this route I'd expect to delete the xml source files and treat the html files as source once things are set up.

yes respec can dump a static version of the file, where it removes the respec processing calls, in fact the final W3C REC versions have to be in that form.

My plan for the examples was to use the re-spec post processing hook to insert mathml-core inline examples, with some client side test to hide those in browsers that don't support it., So the static version of the document would have inline mathml-core examples. but I haven't looked at that yet, just seeing if respec can handle the main part of the document.

[davidcarlisle]

We have been using respec as the master source for a while, closing here.