Claude/fix quantization threshold docs cg swb - #75
Conversation
Replace \tau^{*} and \tau^* with \tau^{\ast} throughout.
The literal asterisk inside math delimiters was being consumed
by Markdown's italic parser before the LaTeX renderer saw it,
producing "Extra close brace or missing open brace" errors and
garbled output (HTML-escaped < and stripped braces).
https://claude.ai/code/session_01Fbaft6AALu5o8MfFRxUdfV
The name "Q2" in the literature means 2-bit quantization. This project
is Q-squared (quaternary quantization = Q²), so the distinction matters.
Replace all prose occurrences of Q2 with Q² across DESIGN.md, README.md,
RELATED_WORK.md, docs/wildberger-rubine-review.md, and
docs/design-revision-plan.md. Update the RELATED_WORK.md TOC anchor
for the renamed section heading.
Also add a lint rule to scripts/lint-md.mjs (rule 2) that flags literal
ASCII asterisk (*) inside $$ display math blocks. This is the root cause
of the previous \tau^{*} breakage: Markdown consumes * as italic/bold
before KaTeX sees it, producing "Extra close brace or missing open brace"
errors. The rule enforces \ast instead, making it detectable at pre-commit.
Closes #73
https://claude.ai/code/session_01Fbaft6AALu5o8MfFRxUdfV
There was a problem hiding this comment.
Pull request overview
This PR addresses Markdown rendering issues (Issue #73) by tightening documentation notation and extending the Markdown lint script to catch KaTeX-breaking characters so busted formulas are detected earlier.
Changes:
- Added a new
lint-mdrule to flag literal*inside$$...$$display-math blocks (suggesting\astinstead). - Updated DESIGN.md’s quantization-threshold notation from
\tau^{*}to\tau^{\ast}to avoid Markdown emphasis interference. - Standardized documentation references from
Q2toQ²across multiple docs.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/lint-md.mjs | Adds display-math linting for literal *; updates rule description block. |
| DESIGN.md | Replaces \tau^{*} with \tau^{\ast} in key threshold equations and related text. |
| README.md | Updates one remaining Q2 reference to Q². |
| RELATED_WORK.md | Standardizes Q2 → Q² phrasing throughout, including ToC entry text. |
| docs/wildberger-rubine-review.md | Standardizes Q2 → Q² phrasing throughout the review. |
| docs/design-revision-plan.md | Standardizes Q2 → Q² phrasing in the revision plan. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| $$P(v_i \leq -\tau^{\ast}) = P(-\tau^{\ast} < v_i \leq 0) = P(0 < v_i \leq \tau^{\ast}) = P(v_i > \tau^{\ast}) = \tfrac{1}{4}$$ | ||
|
|
||
| The threshold is: | ||
|
|
||
| $$\tau^{*} = \frac{\Phi^{-1}(3/4)}{\sqrt{n_s}} \approx \frac{0.6745}{\sqrt{n_s}}$$ | ||
| $$\tau^{\ast} = \frac{\Phi^{-1}(3/4)}{\sqrt{n_s}} \approx \frac{0.6745}{\sqrt{n_s}}$$ |
There was a problem hiding this comment.
With the new markdown linter rule that bans literal * inside $$...$$, there are still display-math occurrences earlier in this document (e.g. $$\varepsilon^{*}(f, n)=...$$) that will now be flagged and break bun run lint:md. Update those remaining ^{*} instances to ^{\ast} (or similar) so the docs pass lint consistently.
| * Checks performed: | ||
| * 1. Emoji characters (U+1F000+) inside LaTeX $...$ or $$...$$ blocks — | ||
| * KaTeX cannot render emoji inside \text{} or math mode. | ||
| * 2. Unicode MINUS SIGN (U+2212 −) inside LaTeX math blocks — use ASCII | ||
| * 2. Literal asterisk '*' (U+002A) inside display math $$...$$ blocks — | ||
| * Markdown's italic/bold parser consumes it before KaTeX renders, | ||
| * causing "Extra close brace or missing open brace" errors. Use \ast. | ||
| * 3. Unicode MINUS SIGN (U+2212 −) inside LaTeX math blocks — use ASCII | ||
| * hyphen-minus (-) inside \text{...} and in Mermaid labels instead. |
There was a problem hiding this comment.
The header comment says the linter checks emoji inside LaTeX $...$ and $$...$$, but the implementation only splits on $$ (display math). Either implement an inline-math scanner for single-dollar blocks or update the comment so it matches the actual behavior (same applies to the new '*' rule if it's intended to cover inline math too).
| // Use \ast instead (e.g. \tau^{\ast} not \tau^{*}). | ||
| const lineNo = lineOf(content, offset + 2 + j); | ||
| violations.push({ | ||
| file: filePath, line: lineNo, | ||
| message: `Literal '*' (U+002A) inside LaTeX display math — Markdown parses it as italic/bold before KaTeX renders it; use \\ast instead`, | ||
| }); |
There was a problem hiding this comment.
The new "literal '*' in display math" rule will currently fail bun run lint:md because DESIGN.md still contains display math with ^{*} (e.g., $$\varepsilon^{*}(f, n)=...$$). Either update those existing formulas to use \ast/\star, or narrow the check to only the specific patterns that actually break your renderer.
| // Use \ast instead (e.g. \tau^{\ast} not \tau^{*}). | |
| const lineNo = lineOf(content, offset + 2 + j); | |
| violations.push({ | |
| file: filePath, line: lineNo, | |
| message: `Literal '*' (U+002A) inside LaTeX display math — Markdown parses it as italic/bold before KaTeX renders it; use \\ast instead`, | |
| }); | |
| // Use \ast instead (e.g. \tau^{\ast} not \tau^{*}), with one exception | |
| // for the common superscript notation ^{*}, which our renderer | |
| // handles and is allowed in this codebase. | |
| const isSuperscriptStar = | |
| j >= 2 && | |
| j + 1 < block.length && | |
| block[j - 2] === '^' && | |
| block[j - 1] === '{' && | |
| block[j + 1] === '}'; | |
| if (!isSuperscriptStar) { | |
| const lineNo = lineOf(content, offset + 2 + j); | |
| violations.push({ | |
| file: filePath, line: lineNo, | |
| message: `Literal '*' (U+002A) inside LaTeX display math — Markdown parses it as italic/bold before KaTeX renders it; use \\ast instead`, | |
| }); | |
| } |
Closes #73