[stacked] Document stacked generated diff layout #160

New issue

Closed

opened 2026-09-21 18:12:38 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-09-21 18:12:38 +00:00

Owner

Original issue: barrettruth/diffs.nvim#366
Original author: barrettruth
Original date: 2026-05-28T02:57:42Z

Part of #358.

Goal

Document stacked generated diff layout accurately and update any dual-rail-specific help text.

Scope

Update :Gdiff and :Greview signatures to include stacked.
Explain that stacked is a generated single-column diffs:// layout with one context-aware line-number rail.
Document exact line-number semantics:
- - lines display old-side line numbers;
- + lines display new-side line numbers;
- context lines display new-side line numbers;
- headers/metadata do not display file line numbers.
Include a small ASCII example that makes repeated numbers around replacements unsurprising.
Update layout parameter descriptions.
Update highlight group wording where current text is dual-rail-specific.

Non-goals

Do not document a public config option unless one is intentionally added in another issue.
Do not describe Pierre-specific web internals.

Acceptance criteria

Vimdoc explains ++layout=stacked for both :Gdiff and :Greview.
The docs make clear that stacked reuses generated unified diff text and differs by rail style.
Highlight group descriptions remain accurate for both dual and single rails.

> Original issue: barrettruth/diffs.nvim#366 > Original author: `barrettruth` > Original date: 2026-05-28T02:57:42Z Part of #358. ## Goal Document stacked generated diff layout accurately and update any dual-rail-specific help text. ## Scope - Update `:Gdiff` and `:Greview` signatures to include `stacked`. - Explain that stacked is a generated single-column `diffs://` layout with one context-aware line-number rail. - Document exact line-number semantics: - `-` lines display old-side line numbers; - `+` lines display new-side line numbers; - context lines display new-side line numbers; - headers/metadata do not display file line numbers. - Include a small ASCII example that makes repeated numbers around replacements unsurprising. - Update layout parameter descriptions. - Update highlight group wording where current text is dual-rail-specific. ## Non-goals - Do not document a public config option unless one is intentionally added in another issue. - Do not describe Pierre-specific web internals. ## Acceptance criteria - Vimdoc explains `++layout=stacked` for both `:Gdiff` and `:Greview`. - The docs make clear that stacked reuses generated unified diff text and differs by rail style. - Highlight group descriptions remain accurate for both dual and single rails.

barrettruth

2026-09-21 18:12:38 +00:00