The Problem With Tags Lists

A Tags List is an alternative to the Agenda that the user can configure with org-agenda-custom-commands. The list shows subheadings that have a certain tag. You can edit these list items with the same commands used for the item on the standard Agenda View. For example, you can invoke org-agenda-todo (bound to t) while on a tag list item to change its TODO state. However, the display doesn't always reflect the action that was performed. That can mislead the user into thinking the command had no effect.

For example, you can change an item's TODO state to DONE. When you do that for an Agenda item, usually Org Agenda removes the item from the Agenda. However, that doesn't happen to an item on a Tags List. The TODO keyword changes to DONE, but the item remains visible. However, if it's a recurring task, the state will remain at "TODO" as if nothing happened. That's because Org reverts the state back to TODO after advancing the date in accordance with the repeater.

The lack of visual feedback can lead the user to invoke the command a second time. Then the item's deadline (or schedule) will be advanced more than once, skipping the next reminder.

Here's a real world example. Suppose the TODO item is a reminder to pay the rent. It's set up with a +1m repeater so that it shows up monthly. The user pays the rent and marks it done. The deadline advances to the next month, which is fine. But nothing changes on the Tags List -- the TODO item is still there. Then the user becomes distracted¹ and forgets that "Pay the Rent" was marked DONE, and so the user marks it DONE again. The deadline advances another month, so the reminder for next month's rent never appears.

A slightly better approach is to filter the Agenda View with org-agenda-tag-filter-preset to avoid generating a Tags List. But I found it tricky to use. I couldn't figure out how to use Customize to include it in one of my org-agenda-custom-commands. Instead I edited my init file to change the custom command from:

;; Dangerous!
("Bm" "Bills for the Month (Recurring)" agenda "Bills"
 ((org-agenda-span 'month) (org-agenda-files '("~/bills.org"))))

…to:

;; Less Dangerous
("Bm" "Bills for the Month (Recurring)" agenda ""
 ((org-agenda-tag-filter-preset '("+bills") nil)))

This is a better approach because when marked DONE, an item's TODO status changes to DONE even if it had a repeater, so the user has a clear indication of its status. Unfortunately, this isn't ideal because the date of the deadline doesn't advance according to the repeater; it's necessary to edit the org file manually to change DONE to TODO and then mark it DONE using org-todo² (which enacts the repeater).

If there were such a thing as org-agenda-todo-before-hook, I'd add a call to org-agenda-check-type and abort if it returned anything other than agenda.

Another approach is to disable org-agenda-todo. I tried it. It works, but it's annoying.

My eventual solution was to modify org-agenda-todo in org-agenda.el³ so that it aborts unless the item is an agenda item. The only required change was adding (org-agenda-check-type nil 'agenda) to the begining of the function. Now when I invoke org-agenda-todo on an item in a Tags List, Emacs responds with "Not allowed in `tags'-type agenda buffer or component." Perfect!

(defun org-agenda-todo (&optional arg)
  "Cycle TODO state of line at point, also in Org file.
This changes the line at point, all other lines in the agenda referring to
the same tree node, and the headline of the tree node in the Org file."
  (interactive "P")
  (org-agenda-check-no-diary)
  (org-agenda-check-type t 'agenda) ;; add this!
  (org-agenda-maybe-loop
   #'org-agenda-todo arg nil nil
   (let* ((col (current-column))

Although this is only a one-line change, it's a good example of why I appreciate Free and Open Source Software (FOSS). Users have the freedom to choose how it operates! In a sense, we're all owners and collaborators. And even if you're not able to make the change on your own, you're part of a supportive community that will help you.

Is there something that irks you about Emacs? Have you asked for help on how to change it? Let's do that now!

---

¹ The hypothetical user is me.

² org-todo operates within org files; org-agenda-todo works from within the Agenda.

³ When modifying an Emacs source file, save a backup of the original and rename the corresponding .elc file. Otherwise Emacs will continue loading the compiled version, making it appear that your changes had no effect. Recompile the modified source if desired.