From 255e24d1e05a33bb7e98c753686e93e26ab3b503 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gabriel=20Fr=C3=B3es=20Franco?= Date: Wed, 3 Jun 2026 14:27:00 +0000 Subject: [PATCH] docs(known-issues): make it the single source of truth Promote known-issues.md to the authoritative divergence reference ahead of retiring development/vimwiki-gap.md: - drop the pointer into vimwiki-gap.md so the file stands alone - reframe the intro as the single source of truth - add an "Internal deferrals (non-parity)" section capturing the cold-path optimizations (RSS render_entry_body disk read, push_level_edit_for_line offset scan, diary neighbor scan) that otherwise only lived in the gap doc, so nothing is lost on deletion Co-Authored-By: Claude Opus 4.8 --- known-issues.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/known-issues.md b/known-issues.md index 76bef81..aa685f9 100644 --- a/known-issues.md +++ b/known-issues.md @@ -5,10 +5,9 @@ not a fork of the original VimL plugin. It targets behavioral parity with vimwiki, but a handful of upstream options and behaviors are implemented differently — or intentionally not at all — because of that architecture. -This page lists what to expect if you're coming from vimwiki. Everything here -is either a deliberate design choice or a tracked future task; none of it is an -accidental bug. For the detailed, per-option parity log (with code references -and test names), see [`development/vimwiki-gap.md`](development/vimwiki-gap.md). +This page is the single source of truth for how nuwiki differs from vimwiki. +Everything here is either a deliberate design choice or a tracked future task; +none of it is an accidental bug. If you hit a behavior that *isn't* listed here and doesn't match vimwiki, please file it — that's a real bug. @@ -108,6 +107,25 @@ self-contained. You can set any of these explicitly to match upstream exactly. --- +## Internal deferrals (non-parity) + +These are not vimwiki differences — they're known low-priority optimizations on +cold code paths, recorded so they aren't rediscovered as "bugs." All are +correct as-is; the deferral is a deliberate risk/reward call. + +- **RSS `render_entry_body` reads from disk.** It re-reads and re-parses each + diary entry from disk rather than reusing an open buffer. This is the *correct* + source of truth for an export artifact — switching to unsaved buffer text would + change semantics, not just performance. +- **`push_level_edit_for_line` scans from offset 0.** The list-level change + (`gl`/`gL`) computes each line's start offset by scanning from the document + start. It's an interactive single-keypress path over small inputs, and the + offset-arithmetic rewrite carries more regression risk than the saved time is + worth. +- **Diary next/prev neighbor scan.** `:VimwikiDiaryNextDay` / `PrevDay` rebuild + and sort the entry list to find one neighbor. Same reasoning — cold path, + small input. + ## Notes - **Third-party plugin compatibility.** A shim at `autoload/vimwiki/vars.vim`