From 8d96906eda19ac94613323deac3c039f88d466e0 Mon Sep 17 00:00:00 2001 From: cashmere Date: Sun, 26 Apr 2026 21:33:26 +0200 Subject: docs(sixel): hard-state img2sixel as the recommended encoder + warn loudly when none is on PATH Users hit a silent-failure mode where `kitty-gfx--sixel-detect' returned true (terminal supports Sixel) but no encoder was on `PATH', so every `sixel-place' logged `no encoder found' and produced no image. The echo-area `message' from `sixel-encode' was easy to miss inside tmux, which made the issue look like a refresh / tmux passthrough bug. - README.org: Requirements section now explicitly lists a Sixel encoder as required and recommends `img2sixel' (libsixel) over ImageMagick, with the concrete numbers from PR #10's bench (~2.2x smaller payload, ~10x faster) and a note that this matters most inside tmux because every refresh re-emits the full DCS payload. Known-Limitations reworded: missing encoder = silent failure surfaced via the debug log. - AGENTS.md: Dependencies block reorganised the same way; adds a pointer to `just sixel-encoder' as the first step when diagnosing Sixel rendering bugs. - kitty-graphics.el: when the active backend is Sixel and `kitty-gfx--sixel-resolve-encoder' returns nil at mode-enable time, fire a `display-warning' (`*Warnings*' buffer + visible message) pointing at img2sixel/ImageMagick, so the failure is no longer buried in /tmp/kitty-gfx.log. --- kitty-graphics.el | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'kitty-graphics.el') diff --git a/kitty-graphics.el b/kitty-graphics.el index c5a1e9d..adfe6b7 100644 --- a/kitty-graphics.el +++ b/kitty-graphics.el @@ -2166,6 +2166,19 @@ The buffer should be writable (caller handles `inhibit-read-only')." (kitty-gfx--query-text-sizing-support)) (kitty-gfx--install-hooks) (kitty-gfx--install-integrations) + ;; Sixel backend silently drops images when no encoder is on + ;; PATH. Warn loudly so users notice before they wonder why + ;; nothing renders. + (when (and (eq kitty-gfx--active-backend 'sixel) + (not (kitty-gfx--sixel-resolve-encoder))) + (kitty-gfx--log "mode: WARNING no Sixel encoder on PATH") + (display-warning + 'kitty-graphics + "Sixel backend active but no encoder on PATH. +Install `img2sixel' (libsixel; strongly recommended) or +ImageMagick (`magick'/`convert'). Without an encoder, no images +will render even though detection reports Sixel as supported." + :warning)) (kitty-gfx--log "mode: enabled (backend=%s cell=%dx%d text-sizing=%s)" kitty-gfx--active-backend kitty-gfx--cell-pixel-width kitty-gfx--cell-pixel-height -- cgit v1.3.1