WebAssembly / WebAssembly/spec
[Spec] Please do not use MathML for non-mathematical items
Nobody has claimed this yet.
- Dominant language
- WebAssembly
- Stars
- 3.5k
- Forks
- 539
- Avg merge
- 2d 1h
- Merged PRs (30d)
- 13
Description
As it currently stands, the specification uses MathML for things like abstract syntax notation and such. Though this works for screen readers, most screen readers treat MathML as a single element, and not a set of characters, without entering certain navigation submodes which don't always provide the necessary visibility. MathML was also not designed for writing abstract syntax; it was designed for mathematical expressions. Thus, it makes it difficult to understand the grammar; for example, when I (a blind individual) read the notation for conventions for the binary format, my screen reader reads the conventions like what follows, which I don't believe was intended:
- Terminal symbols are bytes expressed in hexadecimal notation: 0x0 capital F.
- Nonterminal symbols are written in typewriter font: Val Type comma instr.
- B to the nth power is a sequence of n is greater than or equal to 0 iterations of B.
- B raised to the times power is a possibly empty sequence of iterations of B.
You get the idea. So, to summarize, using MathML in this way (where the expression is not mathematically oriented) only adds superfluous noise and complexity that I have to wade through to understand the specification. In place of MathML where it isn't strictly necessary, I'd strongly consider BNF or a variant, such as EBNF, or PEG notation. I'd be happy to try to submit a PR making these changes, though given the size of the spec that'd be a lot for just one person to do.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
The issue does not name specific files, tests, or entry points. Start by locating the specification sections that use MathML for abstract syntax and binary-format conventions, then review the existing notation and accessibility concerns. Done means replacing non-mathematical MathML with an agreed readable notation across the affected specification content.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- wasm
- Domain
- accessibility, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100