feat(docs): generate Section 5 from function comment headers

The man-page-style comment header above each function in functions/*.fish
becomes the SSOT for that function's documentation. Writing a new function
and documenting it are now the same act.

- manualtools.parse_functions() parses every header carrying a # CATEGORY;
  absence of one is the opt-in, keeping bundled-plugin and prompt internals
  out of the manual with no exclusion list to maintain.
- build-manual.py generates entries for both --concat and --site, with
  **Dependencies:** rendered as links and a **Used by:** reverse index
  computed in one pass. Cross-category links are the navigation win.
- docs/manual/05-functions/*.md reduced to frontmatter-only stubs. Every
  intro measured zero words, so the category files were pure entry
  containers; ordering, titles, and helpKeywords routing are untouched.
- _first_sentence() unwraps the leading hard-wrapped paragraph and skips
  the whole Synopsis block, not just its label line. Site cards no longer
  truncate mid-clause or show a synopsis as their description.

Verification, per the design spec:
- test_concat_roundtrips_original scoped to sections 0-4 and 6-11. It
  guarded a format migration; this is a content migration.
- replaced by structural checks: one entry per categorised function, the
  required sections present, every category resolving to a stub with no
  stub empty, and every declared dependency resolving to a real function
  or a type -q-guarded binary.
- public functions lacking # CATEGORY warn rather than fail, so a new
  user-facing function going undocumented stays visible in CI.

24/24 checks pass. 94 entries generated from 94 parsed headers.

Also drops a stale claim from open-url's NOTES: config-help --html calls
xdg-open directly and has never called open-url.
This commit is contained in:
2026-07-26 04:12:48 -04:00
parent 00f70e8558
commit a65e05b661
24 changed files with 1594 additions and 1601 deletions
@@ -7,48 +7,4 @@ helpKeywords:
- media
---
## dng2avif
Synopsis: dng2avif [-i <file>] [-o <file>] [-q <n>] [-s <n>] [input.dng]
Converts a DNG raw image to a 10-bit HDR AVIF using an ImageMagick,
ffmpeg, avifenc pipeline with metadata sync via exiftool.
-i/--input Input file (or positional arg)
-o/--output Output file (default: same name, .avif extension)
-q/--quality Quality 0-100 (default 92)
-s/--speed Encoding speed 0-10 (default 3)
dng2avif photo.dng
dng2avif -q 85 -s 5 -i shot.dng -o out.avif
## steam-dl
Synopsis: steam-dl
Launches Steam under systemd-inhibit, preventing the system from going
idle or sleeping while a download is in progress.
## spark
Synopsis: spark [--min=<n>] [--max=<n>] [numbers...]
Renders a Unicode sparkline bar chart for a sequence of numbers.
Reads from stdin if no numbers are given.
spark 1 1 2 5 14 42
echo "3 7 2 9 1" | spark
## yt-dlp
Synopsis: yt-dlp [args...] URL [URL...]
Wraps yt-dlp, prepending sane defaults: --sponsorblock-remove all,
--embed-subs, --embed-metadata, and --embed-thumbnail. Each default
is suppressed when you already pass that flag, its alias, or its
negation (e.g. --no-embed-thumbnail drops the thumbnail default;
--no-sponsorblock or your own --sponsorblock-remove drops ours). All
other arguments pass through unchanged, and --help falls through to
real yt-dlp. Opinionated component (C1 aliases); when disabled it
passes straight through to the system yt-dlp.
yt-dlp dQw4w9WgXcQ
yt-dlp --no-embed-thumbnail dQw4w9WgXcQ
---