Crate lattice_help

Expand description

Buffer-backed help model (DESIGN.md §5.11).

Help is a buffer with introspection-collected content – the same underlying type that holds source code. The popup overlay we render today is just one display strategy for this buffer; when multi-buffer support lands the same content can be shown in a split, tab, or window per a user preference (see lattice_core::ui::display::BufferDisplay). This is the emacs model: *Help* is a buffer; its content is queryable, navigable with normal motions, and its links are followable.

Three architectural commitments are baked in here even though the v1 surface only renders the popup:

Content is a lattice_core::Buffer – rope-backed, the same shape as a code buffer. When the help-major-mode + tree- sitter grammar lands (Phase 6+8), motions and the highlighter work over this content with no special-casing.
Links are first-class, in standard markdown form – the formatter emits [label](scheme:value) markdown links and we extract a Vec<HelpLink> listing every reference’s byte range (the LABEL, what the user sees) plus its target ([command, chord, source-location]). Standard markdown link syntax means a help body renders correctly in any markdown viewer (GitHub, docs.rs, this editor’s markdown highlighter); navigation inside the editor dispatches on the URL’s scheme.
Display target is a user preference – BufferDisplay enumerates the surfaces a help buffer can be shown in. v1 implements Popup only; Split / Tab / Window arrive behind multi-buffer.

Markup convention for links inside a help body ([label](url) – standard markdown):

[ex:write](command:ex:write) -> HelpLinkTarget::Command
[zo](key:zo) -> HelpLinkTarget::Chord
[src/foo.rs:42](file:src/foo.rs:42) -> HelpLinkTarget::Source

Anything else (scheme:value with an unrecognized scheme) parses as an unresolved link with the raw URL preserved – forward-compat for future targets (option, event, mode, …).

Modules§

topics: Help topic registry (DESIGN.md §5.11).

Structs§

HelpAnchor: Named scroll target inside a help buffer’s content.
HelpBuffer: One open help buffer. The content is a real [Buffer] (rope- backed), so it composes with everything else that consumes Buffer – search, motions, syntax highlighting (once a help major mode + tree-sitter grammar lands).
HelpContent: M.3.2.c.5: pair of (slim help buffer, parsed metadata) returned from every help factory. The App splits this into:
HelpLink: One [[…]] link inside a help buffer’s content. range is the byte interval within the rendered text (NOT including the [[ ]] delimiters – the renderer can highlight just the inner text or the full match depending on style).
HelpMetadata: M.3.2.c.5: parsed-out metadata that travels alongside a freshly-constructed HelpBuffer. Bundles the data the help-mode owns per-buffer so the App can seed it into buffer_locals[id] at popup-open time. Replaces the links / anchors / highlights fields that used to live directly on HelpBuffer.
InlineCode: PU.1b-2b: build the per-line Style::Link spans for links with NO grammar base — the link-only overlay the host seeds into a help buffer’s ExtraHighlights local so the cells-worker DisplayMatrix carries link styling (the grammar can’t: the [label](url) markup is stripped before it parses, so it never emits a Link capture). Same per-line logic as [overlay_link_styles], just onto an empty base. One inline `code` span found in a help buffer’s text.
PopupSnapshot: Renderer-agnostic snapshot of a help popup’s content + view + metadata, pushed onto the <C-o> back-stack when following a help link swaps the popup’s content in place. PU-A.2: moved here from lattice-host — this is help’s back-stack history, not generic popup state, so it lives with the rest of the help model.

Enums§

HelpLinkTarget: What a [[…]] link points at. Renderers / link-following motions dispatch on this.

Functions§

anchor_line: Look up an anchor by name and return the line it points at.
command_link: Helper for help-content formatters. Renders a command link in standard markdown form: [name](command:name).
escape_link_text: Escape the link syntax’s own punctuation — \, [, ], (, ) — with a backslash, so a label or URL may contain it. Chords are the reason: ]f, di(, da), ci] are ordinary motions and text objects, and unescaped each one ended the label or the URL early. The parsers (extract_links_and_clean, parse_help_links) unescape.
extract_links_and_clean
generate_heading_anchors: Walk lines for ATX-style markdown headings (#, ##, …) and emit a HelpAnchor per heading whose name is the GitHub-style slug. Used by the help-topic loader so authors can write [label](#slug) in markdown bodies and have the link route in- editor without manually-managed anchor lists.
inline_code_spans: HP.2: find every inline `code` span in text.
key_link: Helper for help-content formatters. Renders a chord link in standard markdown form: [chord](key:chord).
link_at: Find the metadata link whose label range contains pos.
link_highlights
mode_link: Helper for help-content formatters. Renders a mode link in standard markdown form: [name](mode:name). Used by :describe-buffer (the “modes active here” section).
one_line: Strip every [label](url) markdown link in text down to just its label and return the cleaned-up text plus a HelpLink per link with its byte range computed against the CLEANED text. This is what the help-buffer constructor uses so the user reads ex:write instead of [ex:write](command:ex:write). The link’s URL still drives navigation – it’s stored on the returned HelpLink::target but the URL bytes don’t appear in the rendered output. Collapse a multi-line diagnostic message to a single line. LSP messages can contain newlines (e.g. rust-analyzer’s “expected Foo, found Bar\n – in fn::method”). The help-buffer’s row layout assumes one row per entry; squash to keep visual alignment.
parse_help_lines: Parse lines into a help buffer + metadata. Walks the joined text once, stripping [label](url) markdown links down to their visible labels and indexing each link’s range against the cleaned text. The buffer’s content is the cleaned text; links land on the metadata.
parse_help_lines_and_anchors: Parse lines + explicit anchors into a help buffer + metadata.
parse_help_links: Walk text, locating every [label](url) markdown link and resolving the URL’s scheme into a typed HelpLinkTarget. Each returned HelpLink’s range covers the LABEL bytes (what the user sees as a clickable token) – the surrounding [, ], (, ), and URL bytes aren’t part of the highlighted range.
slugify_heading: Convert a markdown heading line (“## 1. Tree-sitter, core”) into the GitHub-style slug (“1-tree-sitter-core”) used for intra-doc anchor links. Algorithm:
source_link: Helper for help-content formatters. Renders a source link in standard markdown form: [path:line](file:path:line).
topic_link: Helper for help-content formatters. Renders a topic link in standard markdown form: [name](help:name). Used by :describe-* cross-references.