docs: text objects, motions, debug mode, queue view rename

Problem: vimdoc had no documentation for the new text objects, motions,
debug config, or the pending://queue buffer rename.

Solution: add text object and motion tables to the mappings section,
document all eight <Plug> mappings, add debug field to the config
reference, update config example with new keymap defaults, rename
priority view references to queue throughout the vimdoc.
This commit is contained in:
Barrett Ruth 2026-02-26 16:04:24 -05:00
parent 278a81330f
commit 4f31ae5f10

View file

@ -34,7 +34,7 @@ Features: ~
- Relative date input: `today`, `tomorrow`, `+Nd`, `+Nw`, `+Nm`, weekday - Relative date input: `today`, `tomorrow`, `+Nd`, `+Nw`, `+Nm`, weekday
names, month names, ordinals, and more names, month names, ordinals, and more
- Recurring tasks with automatic next-date spawning on completion - Recurring tasks with automatic next-date spawning on completion
- Two views: category (default) and priority flat list - Two views: category (default) and queue (priority-sorted flat list)
- Multi-level undo (up to 20 `:w` saves, persisted across sessions) - Multi-level undo (up to 20 `:w` saves, persisted across sessions)
- 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` - Quickfix list of overdue/due-today tasks via `:Pending due`
@ -278,13 +278,41 @@ Default buffer-local keys: ~
`<CR>` Toggle complete / uncomplete (`toggle`) `<CR>` Toggle complete / uncomplete (`toggle`)
`!` Toggle the priority flag (`priority`) `!` Toggle the priority flag (`priority`)
`D` Prompt for a due date (`date`) `D` Prompt for a due date (`date`)
`<Tab>` Switch between category / priority view (`view`) `<Tab>` Switch between category / queue view (`view`)
`U` Undo the last `:w` save (`undo`) `U` Undo the last `:w` save (`undo`)
`o` Insert a new task line below (`open_line`) `o` Insert a new task line below (`open_line`)
`O` Insert a new task line above (`open_line_above`) `O` Insert a new task line above (`open_line_above`)
`zc` Fold the current category section (category view only) `zc` Fold the current category section (category view only)
`zo` Unfold the current category section (category view only) `zo` Unfold the current category section (category view only)
Text objects (operator-pending and visual): ~
Key Action ~
------- ------------------------------------------------
`at` Select the current task line (`a_task`)
`it` Select the task description only (`i_task`)
`aC` Select a category: header + tasks + blanks (`a_category`)
`iC` Select inner category: tasks only (`i_category`)
`at` supports count: `d3at` deletes three consecutive tasks. `it` selects
the description text between the checkbox prefix and trailing metadata
tokens (`due:`, `cat:`, `rec:`), making `cit` the natural way to retype a
task description without touching its metadata.
`aC` and `iC` are no-ops in the queue view (no headers to delimit).
Motions (normal, visual, operator-pending): ~
Key Action ~
------- ------------------------------------------------
`]]` Jump to the next category header (`next_header`)
`[[` Jump to the previous category header (`prev_header`)
`]t` Jump to the next task line (`next_task`)
`[t` Jump to the previous task line (`prev_task`)
All motions support count: `3]]` jumps three headers forward. `]]` and
`[[` are no-ops in the queue view. `]t` and `[t` work in both views.
`dd`, `p`, `P`, and `:w` work as standard Vim operations. `dd`, `p`, `P`, and `:w` work as standard Vim operations.
*<Plug>(pending-open)* *<Plug>(pending-open)*
@ -323,6 +351,38 @@ Default buffer-local keys: ~
<Plug>(pending-open-line-above) <Plug>(pending-open-line-above)
Insert a correctly-formatted blank task line above the cursor. Insert a correctly-formatted blank task line above the cursor.
*<Plug>(pending-a-task)*
<Plug>(pending-a-task)
Select the current task line (linewise). Supports count.
*<Plug>(pending-i-task)*
<Plug>(pending-i-task)
Select the task description text (characterwise).
*<Plug>(pending-a-category)*
<Plug>(pending-a-category)
Select a full category section: header, tasks, and surrounding blanks.
*<Plug>(pending-i-category)*
<Plug>(pending-i-category)
Select tasks within a category, excluding the header and blanks.
*<Plug>(pending-next-header)*
<Plug>(pending-next-header)
Jump to the next category header. Supports count.
*<Plug>(pending-prev-header)*
<Plug>(pending-prev-header)
Jump to the previous category header. Supports count.
*<Plug>(pending-next-task)*
<Plug>(pending-next-task)
Jump to the next task line, skipping headers and blanks.
*<Plug>(pending-prev-task)*
<Plug>(pending-prev-task)
Jump to the previous task line, skipping headers and blanks.
Example configuration: >lua Example configuration: >lua
vim.keymap.set('n', '<leader>t', '<Plug>(pending-open)') vim.keymap.set('n', '<leader>t', '<Plug>(pending-open)')
vim.keymap.set('n', '<leader>T', '<Plug>(pending-toggle)') vim.keymap.set('n', '<leader>T', '<Plug>(pending-toggle)')
@ -341,12 +401,12 @@ Category view (default): ~ *pending-view-category*
first within each group. Category sections are foldable with `zc` and first within each group. Category sections are foldable with `zc` and
`zo`. `zo`.
Priority view: ~ *pending-view-priority* Queue view: ~ *pending-view-queue*
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
without a due date sort last), then by internal order. Done tasks appear without a due date sort last), then by internal order. Done tasks appear
after all pending tasks. Category names are shown as right-aligned virtual after all pending tasks. Category names are shown as right-aligned virtual
text alongside the due date virtual text so tasks remain identifiable text alongside the due date virtual text so tasks remain identifiable
across categories. across categories. The buffer is named `pending://queue`.
============================================================================== ==============================================================================
CONFIGURATION *pending-config* CONFIGURATION *pending-config*
@ -371,6 +431,14 @@ loads: >lua
undo = 'U', undo = 'U',
open_line = 'o', open_line = 'o',
open_line_above = 'O', open_line_above = 'O',
a_task = 'at',
i_task = 'it',
a_category = 'aC',
i_category = 'iC',
next_header = ']]',
prev_header = '[[',
next_task = ']t',
prev_task = '[t',
}, },
gcal = { gcal = {
calendar = 'Tasks', calendar = 'Tasks',
@ -429,6 +497,17 @@ Fields: ~
See |pending-mappings| for the full list of actions See |pending-mappings| for the full list of actions
and their default keys. and their default keys.
{debug} (boolean, default: false)
Enable diagnostic logging. When `true`, textobj
motions, mapping registration, and cursor jumps
emit messages at `vim.log.levels.DEBUG`. Use
|:messages| to inspect the output. Useful for
diagnosing keymap conflicts (e.g. `]t` colliding
with Neovim defaults) or motion misbehavior.
Example: >lua
vim.g.pending = { debug = true }
<
{gcal} (table, default: nil) {gcal} (table, default: nil)
Google Calendar sync configuration. See Google Calendar sync configuration. See
|pending.GcalConfig|. Omit this field entirely to |pending.GcalConfig|. Omit this field entirely to