docs: document wip and blocked task states (#99) (#106)

Problem: The vimdoc only describes `pending`/`done`/`deleted` statuses
with no mention of work-in-progress or blocked states.

Solution: Document new `wip` and `blocked` statuses across views (sort
order), filters (new predicates), icons (`>` and `=`), highlight groups
(`PendingWip`, `PendingBlocked`), and the data format schema.
This commit is contained in:
Barrett Ruth 2026-03-08 19:13:57 -04:00 committed by GitHub
parent 36a469e964
commit e534e869a8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -413,14 +413,14 @@ Category view (default): ~ *pending-view-category*
Tasks are grouped under their category header. Categories appear in the Tasks are grouped under their category header. Categories appear in the
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 tasks are sorted by status (wip → pending → blocked → done), then by
first within each group. Category sections are foldable with `zc` and priority, then by insertion order. Category sections are foldable with
`zo`. `zc` and `zo`.
Queue view: ~ *pending-view-queue* 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 status (wip → pending → blocked →
without a due date sort last), then by internal order. Done tasks appear done), then by priority, then by due date (tasks without a due date sort
after all pending tasks. Category names are shown as right-aligned virtual last), then by internal order. 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. The buffer is named `pending://queue`. across categories. The buffer is named `pending://queue`.
@ -452,6 +452,10 @@ Available predicates: ~
`priority` Show only tasks with priority > 0 (the `!` marker). `priority` Show only tasks with priority > 0 (the `!` marker).
`wip` Show only tasks with status `wip` (work in progress).
`blocked` Show only tasks with status `blocked`.
`clear` Special value for |:Pending-filter| — clears the active filter `clear` Special value for |:Pending-filter| — clears the active filter
and shows all tasks. and shows all tasks.
@ -779,14 +783,16 @@ Fields: ~
{icons} (table) *pending.Icons* {icons} (table) *pending.Icons*
Icon characters displayed in the buffer. The Icon characters displayed in the buffer. The
{pending}, {done}, and {priority} characters {pending}, {done}, {priority}, {wip}, and
appear inside brackets (`[icon]`) as an overlay {blocked} characters appear inside brackets
on the checkbox. The {category} character (`[icon]`) as an overlay on the checkbox. The
prefixes both header lines and EOL category {category} character prefixes both header lines
labels. Fields: and EOL category labels. Fields:
{pending} Pending task character. Default: ' ' {pending} Pending task character. Default: ' '
{done} Done task character. Default: 'x' {done} Done task character. Default: 'x'
{priority} Priority task character. Default: '!' {priority} Priority task character. Default: '!'
{wip} Work-in-progress character. Default: '>'
{blocked} Blocked task character. Default: '='
{due} Due date prefix. Default: '.' {due} Due date prefix. Default: '.'
{recur} Recurrence prefix. Default: '~' {recur} Recurrence prefix. Default: '~'
{category} Category prefix. Default: '#' {category} Category prefix. Default: '#'
@ -835,6 +841,14 @@ PendingOverdue Applied to the due date virtual text of overdue tasks.
PendingDone Applied to the text of completed tasks. PendingDone Applied to the text of completed tasks.
Default: links to `Comment`. Default: links to `Comment`.
*PendingWip*
PendingWip Applied to the checkbox icon of work-in-progress tasks.
Default: links to `DiagnosticInfo`.
*PendingBlocked*
PendingBlocked Applied to the checkbox icon and text of blocked tasks.
Default: links to `DiagnosticError`.
*PendingPriority* *PendingPriority*
PendingPriority Applied to the `! ` priority marker on priority tasks. PendingPriority Applied to the `! ` priority marker on priority tasks.
Default: links to `DiagnosticWarn`. Default: links to `DiagnosticWarn`.
@ -1200,7 +1214,8 @@ Schema: >
Task fields: ~ Task fields: ~
{id} (integer) Unique, auto-incrementing task identifier. {id} (integer) Unique, auto-incrementing task identifier.
{description} (string) Task text as shown in the buffer. {description} (string) Task text as shown in the buffer.
{status} (string) `'pending'`, `'done'`, or `'deleted'`. {status} (string) `'pending'`, `'wip'`, `'blocked'`, `'done'`,
or `'deleted'`.
{category} (string) Category name. Defaults to `default_category`. {category} (string) Category name. Defaults to `default_category`.
{priority} (integer) `1` for priority tasks, `0` otherwise. {priority} (integer) `1` for priority tasks, `0` otherwise.
{due} (string) ISO date string `YYYY-MM-DD`, or absent. {due} (string) ISO date string `YYYY-MM-DD`, or absent.