docs: full documentation cleanup (stale files, ARCHITECTURE, READMEs)#18
Merged
Conversation
The TUI mode feature has shipped (src/tui/, default mode), so its implementation plan and manual-QA debug log are spent scaffolding: - docs/TUI_MODE_PLAN.md — 3328-line task plan; checkboxes never maintained. Authoritative design lives in docs/TUI_MODE_DESIGN.md. - docs/TUI_MODE_DEBUG_LOG.md — QA running log; its own conclusion says to delete or archive it once the feature merged. - TEST_PLAN.md — early plan whose central gap (heading-PNG integration test) is now covered by tests/headings.rs. Also drop its now-dangling Cargo.toml exclude entry. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
These captured one-time decision-making that has since shipped: - docs/RESEARCH.md — original large-font-heading feasibility study; untouched since v0.1.0, no references. - docs/TUI_MODE_RESEARCH.md — TUI stack/approach comparison; the chosen approach is built. Drop the now-dangling reference to it from docs/TUI_MODE_DESIGN.md (the surviving authoritative design). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The doc had drifted badly: it listed a six-module layout with a markdown.rs that no longer exists and never mentioned the TUI mode (now the default) or the layout.rs/cat.rs split that defines the codebase. Rewrite against the real src/ tree: - dual output paths sharing one RenderedDoc core (layout::build → cat::print | tui::run), with mode dispatch from main.rs - accurate module overview (cat/layout/tui/frontmatter/theme + tui/*) - RenderedDoc data model (Line/LineKind/Span/Style, headings, images, metadata) and rayon-parallel heading rasterization - cat vs TUI Kitty emission (a=T inline vs transmit-once + per-frame placement diff) - emoji font routing, current platform default families - iTerm2-only echo suppression rationale, XDG config + theme/bell/ metadata/font options Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rrbe
changed the title
Cross-checked the four explainer/design docs against the current source and fixed drift: - MARKDOWN_FEATURE_COVERAGE.md — audit target was src/markdown.rs (deleted); repoint to src/layout.rs. Feature matrix re-verified accurate against layout.rs Options + image placeholder. - TERMINAL_PROTOCOLS.md — test helper renamed extract_kitty_pngs → extract_kitty_frames (+ decode_png). - LINK_PICKER_DESIGN.md — replace brittle mod.rs line-range refs with symbol names (handle_link_select_key, TOC_PANEL_WIDTH); the proposals are still unimplemented (take(9) cap remains) so the doc stays valid. - ITERM2_KITTY_RESPONSE_LEAK.md — markdown::render → layout::build + cat::print; drain_kitty_responses → drain_iterm2_acks. Added a dated note: echo suppression is now iTerm2-only (unconditional ~ECHO tripped Ghostty's Secure Keyboard Entry), correcting the old "harmless everywhere" conclusion. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The READMEs had grown to ~210 lines each. Keep them to a quick start (intro, install, basic usage, terminal support, license) and move the detailed reference into a dedicated guide: - new docs/USAGE.md + docs/USAGE_CN.md: full CLI options, TUI key bindings, configuration (incl. platform default font tables), and known issues. Cross-linked EN ↔ CN. - README.md / README_CN.md: drop the keybinding table, full config section, font tables, and known-issues list; link to the guide. - align bilingual drift: README_CN gains the crates.io install method and Rust-version note it was missing; add an EN ↔ CN link at the top of each README. config.example.toml stays the single source of truth for config defaults; the guide mirrors it (now including the `metadata` key). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rrbe
changed the title
The two demo screenshots are permanent, so a version-less raw URL on master keeps the links current without re-pinning each release — matching the install.sh/uninstall.sh URLs, which already use master. Co-Authored-By: Claude Opus 4.8 (1M context) <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.
A documentation housekeeping pass across the whole repo: drop spent one-time files, re-sync surviving docs with the code, and slim the READMEs down to a quick start.
Removed — spent one-off artifacts
The work these tracked has shipped, so they no longer carry lasting value:
docs/TUI_MODE_PLAN.md— 3328-line task plan; 157 checkboxes never maintained. Design survives indocs/TUI_MODE_DESIGN.md.docs/TUI_MODE_DEBUG_LOG.md— manual-QA log; its own conclusion says to delete it post-merge.TEST_PLAN.md— early plan whose central gap is now covered bytests/headings.rs.docs/RESEARCH.md,docs/TUI_MODE_RESEARCH.md— pre-implementation research; decisions made and built.Refreshed — re-synced with current code
docs/ARCHITECTURE.md— was badly stale (6-module layout, referenced a deletedmarkdown.rs, no TUI mode). Rewritten against the realsrc/tree: dual cat/TUI paths over oneRenderedDoccore, module map, data model, rayon heading rasterization, cat-vs-TUI Kitty emission, emoji routing, iTerm2-only echo suppression, XDG config.docs/MARKDOWN_FEATURE_COVERAGE.md— audit targetmarkdown.rs→layout.rs; feature matrix re-verified.docs/TERMINAL_PROTOCOLS.md— test helperextract_kitty_pngs→extract_kitty_frames.docs/LINK_PICKER_DESIGN.md— brittle line-range refs → symbol names (proposals still unimplemented, doc stays valid).docs/ITERM2_KITTY_RESPONSE_LEAK.md—markdown::render→layout::build/cat::print;drain_kitty_responses→drain_iterm2_acks; added a note that echo suppression is now iTerm2-only (unconditional~ECHOtripped Ghostty's Secure Keyboard Entry), correcting the old "harmless everywhere" claim.Slimmed — READMEs → quick start + guide
docs/USAGE.md+docs/USAGE_CN.md: full CLI options, TUI key bindings, configuration (incl. platform default font tables), known issues. Cross-linked EN ↔ CN.README.md/README_CN.md(~210 → ~115 lines each): keep intro, install, basic usage, terminal support, license; link to the guide. Aligned bilingual drift (README_CN gains crates.io install + Rust-version note; added EN ↔ CN top links).Incidental cleanup
TEST_PLAN.mdentry fromCargo.toml'sexclude.TUI_MODE_RESEARCH.mdreference indocs/TUI_MODE_DESIGN.md.Kept (deliberately)
CONTEXT.md(glossary),docs/adr/(decision records),docs/TUI_MODE_DESIGN.md,docs/LINK_PICKER_DESIGN.md.All internal doc links verified resolvable.
make checkpasses (no source changed in the README/doc commits).🤖 Generated with Claude Code