Skip to content

Correct out-of-date passages in the man pages - #4200

Merged
djmitche merged 3 commits into
GothenburgBitFactory:developfrom
brzzdev:docs/man-page-corrections
Sep 25, 2026
Merged

djmitche merged 3 commits into
GothenburgBitFactory:developfrom
brzzdev:docs/man-page-corrections

Conversation

@brzzdev

@brzzdev brzzdev commented Sep 24, 2026

Copy link
Copy Markdown
Contributor

Several passages in task(1) and taskrc(5) no longer match what Taskwarrior 3.5.0 does.

  • _get exits with 2 for an invalid DOM reference. A missing value prints nothing and exits with 0; the page said both exit with 1.
  • sow, som, soq and soy are the start of the current period, not the next one.
  • The or example said the command line filter needs parentheses to combine correctly with the report filter. Taskwarrior now adds them itself. The section now explains that, and gives an example where parentheses are still needed, when mixing and and or.
  • socw and eocw were never recognised in 3.x, but they were still in the man page and the zsh and fish completions. I removed them, as discussed in 2.6.X: 'eocw' and 'socw' are invalid #3628, and the week headings now say which day each date falls on. soww/eoww refer to the next work week when used on a Sunday.
  • weekstart only changes the calendar layout, week numbers and week dates such as 2026-W02. The taskrc(5) entry now says that it does not affect sow, eow or the WEEK virtual tag.

I checked each change against the source and the 3.5.0 binary with an empty database.

The _get change documents current behaviour. #4196 left open whether a missing value exiting with 0 is intended. If it's a bug, this paragraph should change with the fix.

The website's DOM page had the same tag.<name> problem reported in #4196, and it's fixed separately in GothenburgBitFactory/tw.org#1465.

Closes #4196
Closes #3628

Document the exit status of _get for invalid references and missing
values, describe sow/som/soq/soy as the start of the current period,
and update the 'or' example now that the command line filter is
parenthesized before it is combined with the report filter.  Add an
example of where parentheses are still needed.

Closes #4196
They appear in the man page and the zsh and fish completions, but
Taskwarrior no longer recognizes them.  'sow' and 'eow' already cover
the current week, so remove them rather than add a third notion of
week.  Also state which day each remaining week-relative date falls on.

Closes #3628
The entry only said that it sets the day a week starts, which suggests
that sow, eow and the WEEK virtual tag follow it.  They don't: they
always use a Monday to Sunday week.  weekstart only changes the
calendar layout, week numbers and the meaning of week dates.

@djmitche djmitche left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for these fixes!

I want to clarify for those following along that these represent changes that have occurred sometime in the last ~5 years, and for which documentation wasn't properly updated. 3.0.0 was released during that 5-year period, but these changes weren't specifically associated with that release.

Comment thread doc/man/task.1.in
@djmitche
djmitche merged commit 5632caf into GothenburgBitFactory:develop Sep 25, 2026
16 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

task(1) man page: _get exit status, sow/som/soq/soy, and the OR precedence example are out of date 2.6.X: 'eocw' and 'socw' are invalid

2 participants