Repository navigation
fix(theme): use list markers the marker font actually maps - #258
Merged
Merged
Conversation
The `disc` and `circle` markers used U+26AB MEDIUM BLACK CIRCLE. No font in the marker's chain maps it: not JetBrainsMono, not the copy of M+ 1p bundled with Asciidoctor PDF, not Noto Sans, not Noto Emoji. Depending on the toolchain this either warns WARNING: Could not locate the character `⚫' (⚫) in the following fonts: JetBrainsMono, M+ 1p Fallback, Noto Sans, Noto Emoji or silently substitutes .notdef, rendering every first- and second-level bullet as a missing-glyph box. The `square` marker (U+25A0) is unaffected because JetBrainsMono maps it. U+26AB only ever rendered by accident. It is absent from the marker font and was picked up from fonts/mplus-1p-regular-fallback.ttf, the one font in the chain that happens to carry it. d93e7bf repointed `M+ 1p Fallback` at GEM_FONTS_DIR/mplus1p-regular-fallback.ttf to fix hard-break line height; the two copies have disjoint coverage here — the local one maps U+26AB but not U+000A, the bundled one maps U+000A but not U+26AB — so that change removed the only source of the glyph. Use U+25CF BLACK CIRCLE, which JetBrainsMono maps directly, so the marker resolves in its own font and never enters the fallback chain. Set explicit marker font sizes at the same time: U+25CF at the full body size is larger than the old marker looked, and 0.66em brings the disc to 4.36pt wide against 6.38pt before the regression. Reported by mocenigo, whose marker block and sizes this adopts: riscv/docs-spec-template#118 (comment) Verified by rebuilding a document with three nested list levels and a `+` hard-break block: * disc, circle and square markers all render; no missing-glyph warnings * only Petrona, Montserrat and JetBrainsMono are embedded — no fallback font is pulled in for the markers * hard-break baseline advances stay at 13.979pt, unchanged from d93e7bf Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Signed-off-by: Bill Traynor <wmat@riscv.org>
Collaborator
Author
|
mocenigo (@mocenigo) thanks for the suggestion for this one. |
This was referenced Sep 1, 2026
Tariq Kurd (tariqkurd-repo)
pushed a commit
to riscv/riscv-cheri
that referenced
this pull request
Sep 2, 2026
Supersedes #1204. ## Why The PDF builds are failing on any PR that picks up the `docs-resources` bump to `d93e7bf` ([failing run](https://github.com/riscv/riscv-cheri/actions/runs/33456702369/job/99698095218?pr=1204)). All four PDF targets fail with `Error 1` and no error message, only warnings: ``` asciidoctor: WARNING: Could not locate the character `⚫' (⚫) in the following fonts: JetBrainsMono, M+ 1p Fallback, Noto Sans, Noto Emoji asciidoctor: WARNING: Could not locate the character `✘' (✘) in the following fonts: body, M+ 1p Fallback, Noto Sans, Noto Emoji ``` There is no error — the Makefile passes `--failure-level=WARN`, which promotes these to build failures. `d93e7bf` repointed the `M+ 1p Fallback` theme entry from the copy of M+ 1p in `docs-resources/fonts` to the copy bundled with Asciidoctor PDF, to fix hard-break line height. The two copies have disjoint coverage — the bundled one maps `U+000A` and more CJK, the local one maps ~1240 codepoints the bundled one lacks — so that change removed the only source of `U+26AB` and `U+2718` in the chain. ## What this picks up * **riscv/docs-resources#258** — moves the `disc` and `circle` list markers off `U+26AB` onto `U+25CF`, which JetBrainsMono maps directly, so the marker resolves in its own font instead of entering the fallback chain. * **riscv/docs-resources#259** — appends the local copy of M+ 1p to the end of the fallback chain, restoring `U+2718`. Nothing is removed or reordered: the bundled copy still comes first and still decides line feed and CJK. `U+2718` is used in the privileged integration table in `src/cheri/riscv-priv-integration.adoc`. `U+2714` on the same rows kept resolving, because the bundled copy happens to map it, so the pair rendered inconsistently even before the build began to fail. ## Verification Run locally against `ghcr.io/riscv/riscv-docs-base-container-image:latest`, the image CI uses: * `make -j$(nproc)` — the same command the workflow runs — exits **0** with **zero warnings**, building all 15 artifacts, including the four PDFs that failed in the run above. * Since the Makefile passes `--failure-level=WARN`, exit 0 is itself proof that no warning was emitted. * In the resulting 186-page `riscv-cheri.pdf`, all 19 check/cross glyphs render in `mplus-1p-regular` (13 `✔`, 6 `✘`). The six `✘` were missing-glyph boxes before. ## Note on #1204 #1204 bumps to `d93e7bf`, the commit that introduced the regression, so it should be closed rather than merged. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Signed-off-by: Bill Traynor <wmat@riscv.org> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes the missing-glyph regression reported in riscv/docs-spec-template#118 (comment).
Problem
ulist.marker.discandulist.marker.circlewere set to⚫(U+26AB MEDIUM BLACK CIRCLE). No font in the marker's chain maps that codepoint — not JetBrainsMono (the markerfont-family), not the copy of M+ 1p bundled with Asciidoctor PDF, not Noto Sans, not Noto Emoji.Depending on the toolchain this either warns:
or silently substitutes
.notdef, rendering every first- and second-level bullet as a missing-glyph box.square(U+25A0) is unaffected — JetBrainsMono maps it.Root cause
U+26AB was never in the marker font; it only ever rendered because it was picked up from
fonts/mplus-1p-regular-fallback.ttf, the one font in the chain that happens to carry it.d93e7bf (#256) repointed
M+ 1p FallbackatGEM_FONTS_DIR/mplus1p-regular-fallback.ttfto fix hard-break line height. The two copies have disjoint coverage exactly here:fonts/mplus-1p-regular-fallback.ttfGEM_FONTS_DIR/mplus1p-regular-fallback.ttfSo that change removed the only source of the glyph. The bullets were always relying on an accident of fallback coverage; #256 exposed it.
Fix
Use
●(U+25CF BLACK CIRCLE), which JetBrainsMono maps directly. The marker now resolves in its ownfont-familyand never enters the fallback chain at all, so it cannot break again when the chain changes.Explicit marker font sizes are set at the same time: U+25CF at the full body size renders larger than the old marker appeared, and
0.66embrings the disc to 4.36pt wide against 6.38pt before the regression.This adopts mocenigo (@mocenigo)'s marker block and sizes as proposed in the issue comment, unchanged.
Verification
Rebuilt a document with three nested list levels and a
+hard-break block.Note for reviewers
discandcircleare both●, so list nesting levels 1 and 2 are visually identical. That is not new — the theme already had⚫for both — and it matches what was proposed and validated in the issue. If the level distinction is wanted,circle: ○(U+25CB) or◦(U+25E6) are both in JetBrainsMono and would work at the same size. Left as a follow-up style call.🤖 Generated with Claude Code