Clean up documentation #500
Conversation
| <tr><td>`--mark-effects`</td><td>`markEffects`</td><td>Propagate and render <a href="#effects">effects</a> like "user code".</td></tr> | ||
| <tr><td>`--multipage`</td><td></td><td>Emit a distinct page for each top-level clause.</td></tr> |
There was a problem hiding this comment.
I'm not clear on the difference between "Build options" vs. "Document options", but it does seem strange for markEffects to not be in the same category as toc.
There was a problem hiding this comment.
I'm not entirely clear on the difference either, but I agree markEffects probably ought to be under "document options".
| <!-- what does it even mean for a LHS to be optional??? --> | ||
| <p><b>optional:</b> If present, the LHS is marked as optional.</p> |
There was a problem hiding this comment.
I think this attribute should just be removed, but maybe there's a case I'm just not getting for
<emu-production>
<emu-nt optional="">LHS</emu-nt> <emu-geq>:</emu-geq>
<emu-rhs>…</emu-rhs>
…
</emu-production>There was a problem hiding this comment.
Yeah I have no idea what that's for.
Also, I'm not sure it makes sense to support writing emu-production (etc) manually; the happy path is using grammarkdown notation. Possibly these should not be in the documentation at all. (They'll still be implicitly supported because grammarkdown emits these nodes, but we don't need to tell people about them, I think.)
| <p><b>type:</b> Optional: Type of production. If absent, the production is considered syntactic.</p> | ||
| <ul> | ||
| <li>"lexical": The production is part of a lexical grammar, and should render with the LHS and RHS separated by two colons “<b>::</b>”.</li> | ||
| <li>"regexp": Deprecated because the ECMAScript regular expression grammar is considered to be lexical. Productions with this type render with the LHS and RHS separated by three colons “<b>:::</b>”.</li> | ||
| </ul> |
There was a problem hiding this comment.
I don't like having default values that are not theirselves part of the enumeration... should we just add support for e.g. type="syntactic"?
There was a problem hiding this comment.
I understand that preference, but I prefer to have only one way of writing anything, when possible, so I would prefer to avoid adding an alias here.
The most convenient way to review is probably commit-by-commit with whitespace changes suppressed.