Skip to content

Phase 4: complete the mdBook user guide#88

Merged
cmpute merged 21 commits into
developfrom
guide-v05
Jul 6, 2026
Merged

Phase 4: complete the mdBook user guide#88
cmpute merged 21 commits into
developfrom
guide-v05

Conversation

@cmpute

@cmpute cmpute commented Jun 30, 2026

Copy link
Copy Markdown
Owner

Completes Phase 4 (the mdBook guide) of the v0.5 release plan — every stub/empty page is now filled, KaTeX math rendering is wired up, and a CI build-check guards the build. (mdbook build guide exits 0 with no warnings.)

What's included

Infrastructure

  • guide/book.toml: [output.html] + [preprocessor.katex]; dropped multilingual (removed in mdBook 0.5).
  • .github/workflows/guide.yml: a build-check job (no deploy this phase) that installs mdBook + mdbook-katex and runs mdbook build guide.

Content — all previously stub/empty pages filled

  • Foundation: types.md (CBig added as a numeric type), convert.md (FBig conversions + a CBig section), construct.md (CBig construction + the CachedFBig gaps: extra constructors, direct ConstCache API, !Send/!Sync note, worked cache-reuse example).
  • I/O: io/{index,parse,print,serialize,interop}.md.
  • Operations: ops/{index,basic,cmp,bit,exp_log,trig_n_hyper,num_theory}.md (trig_n_hyper is new).
  • Reference: faq.md, cheatsheet.md.
  • Retrofit: KaTeX on the genuine formulas in types.md/compliance.md; SUMMARY.md cleaned of the dangling Complex entry.

Key decisions

  • Math: mdbook-katex. mdBook 0.5 changed the preprocessor wire protocol, so the released mdbook-katex (0.9.x, mdBook 0.4) is incompatible — CI pins mdBook 0.5.3 + mdbook-katex 0.10.0-alpha from lzanini/mdbook-katex git (--locked, pinned commit). The preprocessor renders math server-side and auto-injects the KaTeX CSS, so no theme/CSS config is needed.
  • No standalone Complex chapter — CBig is documented as a numeric type across the existing pages, exactly like FBig (types/construct/convert/ops/io).
  • CBig complex hyperbolics are noted as deferred to 0.5.x (per the release plan).
  • Build-check only — no GitHub Pages deploy this phase, and the Book badge stays commented.

Verification

mdbook build guide is clean; every example's API was cross-checked against source. Guide Rust blocks aren't compiled in CI (mdBook doesn't build them) — a doctest step could be added later if desired.

🤖 Generated with Claude Code

Jacob Zhong and others added 21 commits June 30, 2026 14:19
@claude
Add mdBook guide infra: KaTeX preprocessor + CI build-check
4c6bdc9 
- guide/book.toml: add [output.html] (git-repo + edit links) and
  [preprocessor.katex]; drop `multilingual` (removed in mdBook 0.5).
- .github/workflows/guide.yml: build-check job that installs mdBook 0.5.3 and
  mdbook-katex (0.10.0-alpha from upstream git, pinned commit) then runs
  `mdbook build guide`. Build-check only — no deploy this phase.

The released mdbook-katex crate (0.9.x, built on mdBook 0.4) is incompatible
with mdBook 0.5's preprocessor protocol, hence the pinned git alpha. mdbook-katex
0.10.0-alpha renders math server-side and auto-injects the KaTeX CSS, so no
theme/CSS config is needed.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide Batch 1: foundation pages — types/convert/construct
6ee05c0 
- types.md: add CBig as a numeric type (two-Repr-over-shared-Context model,
  C99 Annex G no-NaN model, ZERO/ONE/I constants).
- convert.md: fill the FBig/DBig conversion sections (precision/base/rounding,
  integers & primitive floats, RBig interop) and add a CBig conversions section.
- construct.md: add CBig constants/from_parts/cbig! macro, and fill the
  CachedFBig gaps (extra constructors, direct ConstCache API, !Send/!Sync
  note, worked cache-reuse example).

Math now uses KaTeX ($...$) per the mdbook-katex setup.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide Batch 2: I/O pages — parse/print/serialize/interop/index
04f84a1 
- index.md: hub linking the I/O topics.
- print.md: integer (Display/Binary/Octal/Hex/in_radix), float (Display and
  scientific e/E/@ markers), rational (num/den + in_expanded repetend), and
  complex (algebraic a+bi) formatting; the existing Debug head..tail section
  is kept verbatim.
- parse.md: FromStr / from_str_radix for each type, incl. the float exponent
  forms and the complex algebraic grammar.
- serialize.md: bytes / serde / rkyv.
- interop.md: to_digits/from_digits, byte access, word access.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide Batch 3: Operations pages (7, incl. new trig_n_hyper)
a08aded 
- index.md: operations hub.
- basic.md: arithmetic per type (integer/float/rational/complex) + mixed-type note.
- cmp.md: equality, ordering, sign, AbsOrd, NumOrd/NumHash.
- bit.md: bitwise ops, BitTest (bit/bit_len), set/clear/trailing_zeros, shifts,
  UBig as a bit vector.
- exp_log.md: two-layer API; real exp/log/powers/roots/constants; complex
  exp/ln/sqrt/pow with the exp/log identities and the branch cut.
- trig_n_hyper.md (NEW): real + complex circular trig and real hyperbolic;
  complex hyperbolics noted as deferred to 0.5.x.
- num_theory.md: Gcd/ExtendedGcd, ConstDivisor/Reduced modular arithmetic.
- SUMMARY.md: add the Trigonometric and Hyperbolic Functions entry.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide Batch 4: reference pages — faq, cheatsheet
19652f2 
- faq.md: why "dashu" (大数 pinyin), a comparison table vs num-bigint/ibig/rug
  (with a malachite note), known limitations, and the MSRV & feature policy.
- cheatsheet.md: dense reference tables for types, construction, conversion,
  operators, formatting, and key methods (with CBig rows throughout).

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide Batch 5: KaTeX retrofit + SUMMARY cleanup
cf4a3c1 
- Retrofit the genuine math formulas in types.md and compliance.md to KaTeX
  (significand×base^exponent, the |error|<1 ulp bound, the Kahan branch-cut
  identity log(-r±i·0)=ln r±iπ, and the arg(0±i∞)=±π/2 values); leave the
  dense table value-mappings as readable Unicode.
- SUMMARY.md: drop the dangling [Complex Numbers](./complex.md) entry; the
  orphan 1-line stub is removed from disk.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
types.md: restyle Complex section as "Layout of CBig"; add ConstCache…
caa0156 
… + FpResult/CfpResult

- Restyle the CBig section as "Layout of `CBig`" to match the Layout of
  UBig/FBig sections (layout-focused prose, same tone).
- Auxiliary Types: broaden the intro (the types span dashu-base/-float/-cmplx)
  and add ConstCache (the reusable math-constant cache) and FpResult/CfpResult
  (the context-layer result types, with the FpError variants).

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide: demote all page headings by one level (H1 → H2)
45694c8 
The page-title H1s caused formatting issues in mdBook's theme, so the top
heading of every sub-document is now H2 (SUMMARY.md untouched). All
sub-headings shift down one level too, preserving the hierarchy. Internal
links are unaffected — anchors derive from heading text, not level.

Applied with a fence-aware transform; no code-block content was changed
(verified: zero `#`-leading lines exist inside any code fence).

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Add CBig::NEG_ONE; document it in the guide
b290a16 
The guide's Constants section listed ::NEG_ONE for the other signed types but
CBig didn't define it, so add the constant for real:

- complex/src/cbig.rs: add `CBig::NEG_ONE` (`-1 + 0i`), mirroring FBig::NEG_ONE;
  extend the `constants` unit test (non-zero, distinct from ONE).
- guide/src/construct.md: list `::NEG_ONE` on the CBig constants line.
- complex/CHANGELOG.md: Unreleased ### Add entry.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide: split Cached Arithmetic into its own chapter
8202e31 
Move "Cached Arithmetic for FBig" out of construct.md into a new top-level
chapter cached.md, as a sibling of Construction and Destruction. Repoint the
CachedFBig cross-references in types.md (×2) and ops/exp_log.md to the new
page; construct.md now covers only construction/destruction.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide: promote cached.md subsections to H2 (now a top-level chapter)
d744959 
Now that Cached Arithmetic is its own chapter, the redundant
`## Cached Arithmetic for FBig` title heading is removed (the title comes
from SUMMARY.md) and the seven subsections — Creation, Cache sharing,
Inspecting/clearing, More constructors, Computing constants, Thread safety,
Worked example — are promoted from H3 to H2, matching construct.md's shape.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide/convert: fold CBig into the type-conversion table
49505f4 
Drop the standalone "Conversion for CBig" section and represent CBig in the
"Conversion among Types" table instead — added a CBig row (From FBig/UBig/IBig)
and column (TryFrom to FBig/IBig), which is where its big-to-big conversions
actually live.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Implement TryFrom<CBig> for UBig
3302b49 
Add the missing CBig → UBig conversion: it succeeds only when the value is
purely real, finite, integer-valued, and non-negative, composing
CBig → FBig → UBig (mirroring the existing TryFrom<CBig> for IBig). Covered by
a new try_from_ubig_composes test (ok / negative→OutOfBounds / fractional and
nonzero-imaginary→LossOfPrecision); clippy-clean.

- complex/src/convert.rs: impl + test.
- complex/CHANGELOG.md: Unreleased ### Add entry.
- guide/src/convert.md: the CBig→UBig table cell is now "TryFrom" (was "—").

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Implement CBig primitive conversions (both directions)
683381d 
Add direct primitive <-> CBig conversions, all composing through FBig and
mirroring dashu-float's surface:
- From<u8..u128, i8..i128> for CBig (integers, any base)
- TryFrom<f32>/<f64> for CBig (base-2; NaN rejected, infinities preserved)
- TryFrom<CBig> for every integer primitive (any base) and for f32/f64 (base-2)

Generated by two local macros (dashu-float's conversion macros are
crate-private, so they can't be reused). Covered by a new primitive_conversions
test; clippy-clean.

Guide: the primitive conversion tables now include a CBig row (fulfilling the
earlier request, now that the impls exist), and complex CHANGELOG records it.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide/convert: clarify CBig's float conversion in the primitive table
43a8e9d 
The big-to-primitive note recommends .to_f*(), but CBig has no such methods —
its only float-conversion path is TryInto (base-2). State that explicitly so
the CBig row (TryInto, no .to_f*()) isn't surprising.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide: drop duplicate page-title headings, promote subsections
a46a1f0 
16 pages opened with a `## Title` identical to their SUMMARY.md entry (e.g.
`## Printing`), which rendered as a duplicate of the sidebar title. Remove
that title heading (SUMMARY.md provides the title) and promote the page's
subsections up one level so they become the top-level sections.

Fence-aware transform; verified no H1 was created and no code block was
touched. Re-scan confirms 0 remaining duplicates; build is clean.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide: use dashu::module:: paths instead of dashu_X::
6fdb288 
Replace the sub-crate paths dashu_base/int/float/ratio/cmplx:: with the
meta-crate paths dashu::base/integer/float/rational/complex:: throughout the
guide. Also fix index.md's meta-crate section, which had the wrong module
names (dashu::int, dashu::ratio) and the wrong alias (dashu::Ratio); it now
lists the correct modules and the dashu::Complex alias.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide/print: move Debug Print to the end; show every type's debug output
ac7e552 
Move the Debug Print section to the end of the Printing page (after the
Display sections) and replace the integer-only examples with one
comprehensive block showing the {:?} output of every numeric kind —
UBig/IBig, FBig/DBig, CachedFBig, RBig, CBig — with each string verified
against the actual implementation.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide/print: show {:#?} output for every numeric type
7250fce 
Replace the integer-only verbose-form example with one that pretty-prints
every kind (UBig, FBig, DBig, CachedFBig, RBig, CBig), each output verified
against the implementation. Output shown via a text block since {:#?} is
multi-line.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide: move "Two-layer API" from exp_log to types
ced7f09 
The two-layer (Context vs convenience) design applies to all inexact
operations, not just exp/log/pow, so move it from the Exponential and
Logarithm page to types.md as a general design section (and trim the now-
redundant convenience-layer sentence from the FpResult subsection).
exp_log.md keeps a one-line forward-reference.

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Guide/num_theory: document the Montgomery reducer
f3933c3 
Add a "Montgomery reducer" section covering MontgomeryRepr/Montgomery
(Montgomery-form modular arithmetic for odd moduli), with the
Montgomery-vs-Barrett (Reduced) trade-off guidance and a worked example
(Fermat's little theorem on a Mersenne prime) adapted from the crate's
verified doctest.

Co-Authored-By: Claude <noreply@anthropic.com>
@cmpute cmpute merged commit ccd7000 into develop Jul 6, 2026
16 checks passed
@cmpute cmpute deleted the guide-v05 branch July 6, 2026 14:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@cmpute