WebAssembly / WebAssembly/spec

[Spec] Please do not use MathML for non-mathematical items

Open
#1,672 6 comments 3 reactions 0 assignees View on GitHub

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.