docs/ux: make :Preview output more discoverable on failure #80

New issue

Closed

opened 2026-04-25 21:38:52 +00:00 by barrettruth · 1 comment

barrettruth commented

2026-04-25 21:38:52 +00:00

Follow-up to #70.

Problem

preview.nvim now has a solid raw-output inspection path through :Preview output and preview.result(), but that path is still easy to miss when the only visible signal is a generic compilation failed notification.

There is also an expectation mismatch for long-running providers like Typst watch: :Preview output is effectively the current watch-session log, whereas one-shot providers behave more like “latest compile output”. That distinction is reasonable, but it should be discoverable and documented instead of being surprising.

Direction

Improve README/help/FAQ guidance around failure workflows:
- diagnostics or quickfix first when available
- :Preview output / preview.result() for raw compiler output
Clarify the output-view semantics for long-running providers versus one-shot compilers.
Consider a minimal failure hint such as compilation failed; see :Preview output only when no structured errors were surfaced.
Keep the generic failure notifier simple; do not reintroduce heuristic line-picking into the general path.

Follow-up to #70. ## Problem `preview.nvim` now has a solid raw-output inspection path through `:Preview output` and `preview.result()`, but that path is still easy to miss when the only visible signal is a generic `compilation failed` notification. There is also an expectation mismatch for long-running providers like Typst watch: `:Preview output` is effectively the current watch-session log, whereas one-shot providers behave more like “latest compile output”. That distinction is reasonable, but it should be discoverable and documented instead of being surprising. ## Direction - Improve README/help/FAQ guidance around failure workflows: - diagnostics or quickfix first when available - `:Preview output` / `preview.result()` for raw compiler output - Clarify the output-view semantics for long-running providers versus one-shot compilers. - Consider a minimal failure hint such as `compilation failed; see :Preview output` only when no structured errors were surfaced. - Keep the generic failure notifier simple; do not reintroduce heuristic line-picking into the general path.

barrettruth commented

2026-04-25 23:32:38 +00:00

closed by #84