0xMiden/miden-vm

Instruction reference docs: `\begin{cases}` blocks are missing the `\\` row separator, breaking KaTeX rendering (41 occurrences across 4 files)

Open

#3,650 opened on Aug 15, 2026

 (0 comments) (0 reactions) (0 assignees)Rust (303 forks)github user discovery
documentationgood first issue

Repository metrics

Stars
 (753 stars)
PR merge metrics
 (Avg merge 6d 2h) (71 merged PRs in 30d)

Description

Summary

Every \begin{cases}...\end{cases} LaTeX block in the core Miden Assembly instruction-reference docs is missing the \\ row separator between the two cases. This is invalid LaTeX/KaTeX syntax and will either throw a render error or merge the two rows incorrectly, since these docs are built with remark-math + rehype-katex (standard KaTeX), which strictly requires \\ to separate rows inside cases (and other array-like environments) — see docs/docusaurus.config.ts.

Example (from u32_operations.md)

Current (broken):

$b \leftarrow \begin{cases} 1, & \text{if}\ a < 2^{32}  0, & \text{otherwise}\ \end{cases}$

Note there's nothing at all between 2^{32} and 0, & — no \\.

Should be:

$b \leftarrow \begin{cases} 1, & \text{if}\ a < 2^{32} \\ 0, & \text{otherwise}\ \end{cases}$

Scope

Checked every \begin{cases} occurrence across the instruction-reference docs — all of them have this defect (41 total, 0 correct):

File Occurrences (all missing \\)
docs/src/user_docs/assembly/instruction_reference.md 16
docs/src/user_docs/assembly/u32_operations.md 11
docs/src/user_docs/assembly/field_operations.md 8
docs/src/user_docs/assembly/stack_manipulation.md 6

This affects the stack-transition description of very commonly used instructions, including eq, neq, lt, u32test, u32testw, u32widening_add, u32overflowing_add, u32overflowing_sub, and others — i.e. a meaningful chunk of the primary reference page anyone learning Miden Assembly would consult.

Why this isn't just a typo

This isn't a wording nit — it's a rendering defect that makes the affected formulas either fail to render (KaTeX parse error) or display incorrectly, directly undermining the "if(condition) then 1 else 0" semantics the docs are trying to convey for these instructions. Given CONTRIBUTING.md's bar of "materially improve clarity," I'd consider this in scope since it currently harms clarity/correctness of rendered math rather than being a cosmetic wording change.

Proposed fix

Add the missing \\ before the second case in each of the 41 blocks. I'm happy to do this myself, split into one PR per file (or one PR total, if preferred) if assigned — didn't want to open a PR without an issue/ assignment per the contributing guidelines.

Contributor guide