docs: update vimdoc to reflect current feature set

Problem: doc/pending.txt was written before the undo stack, folds,
:Pending due, D mapping, and BufEnter reload were added. Several
entries were factually wrong (single-level undo, d vs D key,
:Pending undo listed as non-existent) and highlight group defaults
referenced stale hex colours.

Solution: correct all factual errors and add missing entries —
:Pending due command, :Pending undo command, zc/zo fold mappings,
PendingOverdue highlight group, semantic link defaults for all groups,
category fold docs, BufEnter auto-reload note, and multi-level undo
description.
This commit is contained in:
Barrett Ruth 2026-02-24 19:53:43 -05:00 committed by Barrett Ruth
parent cee0560341
commit 586a8e81e3

View file

@ -33,8 +33,10 @@ Features: ~
- Inline metadata syntax: `due:` and `cat:` tokens parsed on `:w` - Inline metadata syntax: `due:` and `cat:` tokens parsed on `:w`
- Relative date input: `today`, `tomorrow`, `+Nd`, weekday names - Relative date input: `today`, `tomorrow`, `+Nd`, weekday names
- Two views: category (default) and priority flat list - Two views: category (default) and priority flat list
- Single-level undo for the last `:w` save - Multi-level undo (up to 20 `:w` saves, session-only)
- Quick-add from the command line with `:Pending add` - Quick-add from the command line with `:Pending add`
- Quickfix list of overdue/due-today tasks via `:Pending due`
- Foldable category sections (`zc`/`zo`) in category view
- Google Calendar one-way push via OAuth PKCE - Google Calendar one-way push via OAuth PKCE
============================================================================== ==============================================================================
@ -81,7 +83,8 @@ Buffer-local keys are set automatically when the buffer opens. See
The buffer uses `buftype=acwrite` so `:w` always routes through pending.nvim's The buffer uses `buftype=acwrite` so `:w` always routes through pending.nvim's
write handler rather than writing to disk directly. The `pending://` buffer write handler rather than writing to disk directly. The `pending://` buffer
persists across window switches; reopening with `:Pending` focuses the persists across window switches; reopening with `:Pending` focuses the
existing window if one is open. existing window if one is open. The buffer is automatically reloaded from
disk when entered unmodified.
============================================================================== ==============================================================================
INLINE METADATA *pending-metadata* INLINE METADATA *pending-metadata*
@ -143,6 +146,11 @@ COMMANDS *pending-commands*
:Pending archive 7 " remove tasks completed more than 7 days ago :Pending archive 7 " remove tasks completed more than 7 days ago
< <
*:Pending-due*
:Pending due
Populate the quickfix list with all tasks that are overdue or due today.
Open the list with |:copen| to navigate to each task's category.
*:Pending-sync* *:Pending-sync*
:Pending sync :Pending sync
Push pending tasks that have a due date to Google Calendar as all-day Push pending tasks that have a due date to Google Calendar as all-day
@ -151,9 +159,9 @@ COMMANDS *pending-commands*
*:Pending-undo* *:Pending-undo*
:Pending undo :Pending undo
There is no `:Pending undo` subcommand. Use the `U` buffer-local key Undo the last `:w` save, restoring the task store to its previous state.
(see |pending-mappings|) to undo the last `:w` save while the task buffer Equivalent to the `U` buffer-local key (see |pending-mappings|). Up to 20
is open. levels of undo are retained per session.
============================================================================== ==============================================================================
MAPPINGS *pending-mappings* MAPPINGS *pending-mappings*
@ -167,12 +175,16 @@ Buffer-local keys: ~
------- ------------------------------------------------ ------- ------------------------------------------------
`<CR>` Toggle complete / uncomplete the task at cursor `<CR>` Toggle complete / uncomplete the task at cursor
`!` Toggle the priority flag on the task at cursor `!` Toggle the priority flag on the task at cursor
`d` Prompt for a due date on the task at cursor `D` Prompt for a due date on the task at cursor
`<Tab>` Switch between category view and priority view `<Tab>` Switch between category view and priority view
`U` Undo the last `:w` save `U` Undo the last `:w` save
`g?` Show a help popup with available keys `g?` Show a help popup with available keys
`zc` Fold the current category section (category view only)
`zo` Unfold the current category section (category view only)
Standard Vim keys `o`, `O`, `dd`, `p`, `P`, and `:w` work as expected. `o` and `O` are overridden to insert a correctly-formatted blank task line
at the position below or above the cursor rather than using standard Vim
indentation. `dd`, `p`, `P`, and `:w` work as expected.
*<Plug>(pending-open)* *<Plug>(pending-open)*
<Plug>(pending-open) <Plug>(pending-open)
@ -209,7 +221,8 @@ Category view (default): ~ *pending-view-category*
order tasks were added unless `category_order` is set (see order tasks were added unless `category_order` is set (see
|pending-config|). Blank lines separate categories. Within each category, |pending-config|). Blank lines separate categories. Within each category,
pending tasks appear before done tasks. Priority tasks (`!`) are sorted pending tasks appear before done tasks. Priority tasks (`!`) are sorted
first within each group. first within each group. Category sections are foldable with `zc` and
`zo`.
Priority view: ~ *pending-view-priority* Priority view: ~ *pending-view-priority*
A flat list of all tasks sorted by priority, then by due date (tasks A flat list of all tasks sorted by priority, then by due date (tasks
@ -339,20 +352,24 @@ pending.nvim defines the following highlight groups. All groups are set with
*PendingHeader* *PendingHeader*
PendingHeader Applied to category header lines (text at column 0). PendingHeader Applied to category header lines (text at column 0).
Default: bold. Default: links to `Title`.
*PendingDue* *PendingDue*
PendingDue Applied to the due date virtual text shown at the right PendingDue Applied to the due date virtual text shown at the right
margin of each task line. margin of each task line.
Default: fg=#888888, italic. Default: links to `DiagnosticHint`.
*PendingOverdue*
PendingOverdue Applied to the due date virtual text of overdue tasks.
Default: links to `DiagnosticError`.
*PendingDone* *PendingDone*
PendingDone Applied to the text of completed tasks. PendingDone Applied to the text of completed tasks.
Default: strikethrough, fg=#666666. Default: links to `Comment`.
*PendingPriority* *PendingPriority*
PendingPriority Applied to the `! ` priority marker on priority tasks. PendingPriority Applied to the `! ` priority marker on priority tasks.
Default: fg=#e06c75, bold. Default: links to `DiagnosticWarn`.
To override a group in your colorscheme or config: >lua To override a group in your colorscheme or config: >lua
vim.api.nvim_set_hl(0, 'PendingDue', { fg = '#aaaaaa', italic = true }) vim.api.nvim_set_hl(0, 'PendingDue', { fg = '#aaaaaa', italic = true })