Sphinx provides a directive, productionlist (http://sphinx-doc.org/markup/para.html#directive-productionlist) that is used for presenting basic grammar definitions. The primary feature is that it'll link between tokens, so you can define what a statement or a block are, and every other definition making use of those tokens/definitions will link directly to them. Our current format is pretty informal.
There are a few things that make me hesitate to just convert them:
While I can read a BNF when I need to, I don't have any experience writing them (I suspect it will take me a while to gain momentum)
There's no guarantee the typical documentation consumer will be able to read them if we put them in this format, and I imagine the format takes a little more work to understand for everyone (though it removes much more ambiguity).
We'd have to add a number of language pages (or at least a file documenting the basic atoms of the language) to have everything the more complex definitions depend on defined.
The BNF, when output for the plaintext documentation, wouldn't have the advantage of linking to other token definitions, so the cost of the harder-to-read format increases without much corresponding benefit (aside from reduced ambiguity).
Another possibility is that we could provide both forms at some point (a simple syntax summary, and a BNF for better understanding).
Sphinx provides a directive,
productionlist(http://sphinx-doc.org/markup/para.html#directive-productionlist) that is used for presenting basic grammar definitions. The primary feature is that it'll link between tokens, so you can define what a statement or a block are, and every other definition making use of those tokens/definitions will link directly to them. Our current format is pretty informal.There are a few things that make me hesitate to just convert them:
Another possibility is that we could provide both forms at some point (a simple syntax summary, and a BNF for better understanding).