xr09/zeal-docs

Zeal / Dash offline documentation

Zeal (the Linux equivalent of macOS Dash) stores downloaded documentation as .docset bundles: a SQLite index plus local HTML. This skill reads that data directly so you can look things up offline and cite authoritative docs instead of guessing. Docsets contain both API reference (functions, methods, flags) and narrative content (tutorials, how-to guides, explanations).

The helper script lives at scripts/zeal_docs.py inside this skill's directory. Set the path once per session using the absolute location of this skill:

ZD="python3 /path/to/zeal-docs/scripts/zeal_docs.py"

Replace /path/to/zeal-docs with the directory where this skill is installed (i.e. the directory containing this SKILL.md file).

When to use

Use it proactively during programming tasks when a matching docset is installed, especially to:

• Verify a function/method signature, parameters, or defaults.
• Check a return type, raised exceptions, or edge-case behavior.
• Confirm a CLI flag, config directive, or SQL clause syntax.
• Answer how-to / conceptual questions ("how do I bind SQL parameters", "how does transaction control work") — indexed as Guide/Section entries.

If no docset covers the technology (check with list), skip the skill and proceed normally. Docset versions match the user's dev environment — treat them as authoritative; do not "correct" them from memory.

Commands

$ZD list                    # docsets + entry counts
$ZD list --types            # entry types per docset (for search -t)
$ZD search QUERY [-d DOCSET] [-t TYPE] [-n N]
$ZD show REF [--full | --toc | --section TEXT] [--max-chars N]

search prints one line per hit — type, name, tab, then the REF to pass to show:

[Function] json.loads	Python_3::doc/library/json.html#json.loads

How to write good queries

Symbol lookups — use the qualified-name fragment, the way that language writes it: json.loads, Vec::push, context.WithTimeout, QuerySet.filter. Add -d (docset name prefix: -d py, -d post) and -t to cut noise.

Topic / how-to lookups — think "what words are in the section title", not "how would I ask a person":

• Use 1–3 distinctive content words: placeholders, transaction control, error handling — not "how do I safely insert values".
• Multi-word queries require all words in the title, any order (flow control finds "More Control Flow Tools"). If nothing matches all words, the tool automatically retries without filler words, then with any-word matching — a (fallback: ...) note on stderr tells you which.
• Prefer word stems: placeholder matches both "placeholder" and "placeholders"; handle matches "handles"/"handling". Substring matching means shorter is more forgiving.
• Useful -t values: Guide and Section are the narrative/how-to entries in most docsets; Sample in Go is runnable example programs; Command in Redis; Query/Statement for SQL syntax. Run list --types to see what a docset actually uses.

Reading results efficiently

• A ref with #anchor shows just that entry (signature + description + examples). A ref without one renders the whole page.
• For a long page (guides, Redis commands), don't dump it: run --toc first to see the heading outline, then --section "heading text" to render only the part you need. This also skips irrelevant noise (e.g. Redis pages embed every client SDK's signatures; --section Options avoids all of it).
• If a show returns only a bare signature, it's a stub entry (the output says so) — retry with --toc/--section or --full.
• --max-chars defaults to 6000; raise it or pass 0 when you need a full section, lower it when scouting.

Worked examples

# exact signature check
$ZD search "dataclasses.field" -d py
$ZD show "Python_3::doc/library/dataclasses.html#dataclasses.field"

# how-to: parameterized SQL in Python
$ZD search "placeholders" -d py            # → Section entry, show it directly

# scout a big topic page, then read one part
$ZD show "Python_3::doc/library/sqlite3.html" --toc
$ZD show "Python_3::doc/library/sqlite3.html" --section "row factories"

# runnable Go example programs
$ZD search "Rows" -d go -t Sample

Notes

• Read-only and offline; never launches the Zeal GUI or touches the network.
• Docsets dir comes from ~/.config/Zeal/Zeal.conf ([docsets] path); override with --docsets-dir or ZEAL_DOCSETS_DIR.
• Stdlib docsets don't cover third-party packages (e.g. Rust std has no SQLite; Go's database/sql is the driver-agnostic API). If search finds nothing, say so rather than inventing an API.
• Requires python3 with beautifulsoup4 (present on this machine).