Org Agenda is a legendary feature. One of its selling points is customizability (as is usual in Emacs in general). This, however, comes at a price: agenda generating is slow, even though it is reportedly heavily optimized. (At the worst moment, my agenda took about half a minute to generate. A naive benchmark convinced me that the reason was a rather large Org file, weighing almost a megabyte and containing several thousand headlines (a.k.a. capture.org). No surprise, and a good candidate for optimizing on my side (most of its entries do not really need to be even considered for agenda, so those which do can be moved to another file, and this one can be excluded from agenda generation).
But today, I’d like to talk about something else – two of the many options governing agenda generation, namely org-agenda-todo-ignore-with-date and org-agenda-todo-ignore-timestamp.
These two options are just barely mentioned in the Org manual, so let’s look at their docstrings. Here are two excerpts.
org-agenda-todo-ignore-with-date is a variable defined in ‘org-agenda.el’. Its value is t Original value was nil Documentation: Non-nil means don’t show entries with a date in the global todo list. You can use this if you prefer to mark mere appointments with a TODO keyword, but don’t want them to show up in the TODO list. When this is set, it also covers deadlines and scheduled items, the settings of ‘org-agenda-todo-ignore-scheduled’ and ‘org-agenda-todo-ignore-deadlines’ will be ignored.
org-agenda-todo-ignore-timestamp is a variable defined in ‘org-agenda.el’.
Its value is ‘all’
Original value was nil
Documentation:
Non-nil means don’t show entries with a timestamp.
This applies when creating the global todo list.
Valid values are:
past Don’t show entries for today or in the past.
future Don’t show entries with a timestamp in the future.
The idea behind this is that if it has a future
timestamp, you don’t want to think about it until the
date.
all Don’t show any entries with a timestamp in the global todo list.
The idea behind this is that by setting a timestamp, you
have already "taken care" of this item.
It is not easy to tell from them the difference (at least if org-agenda-todo-ignore-timestamp is set to all). So, I did what had to be done, and looked into the source code. There, I found the cutely named function org-agenda-check-for-timestamp-as-reason-to-ignore-todo-item (in org-agenda.el). As it turned out, the story is quite simple. org-agenda-todo-ignore-with-date ignores a heading if it has any (active) timestamp, not necessarily in the headline itself. On the other hand, org-agenda-todo-ignore-timestamp takes into account the first active timestamp which is not “deadline” nor “scheduled”. (Also, it is probably way slower.)
In particular, this means that if you have org-agenda-todo-ignore-with-date set to t, it doesn’t make sense to set org-agenda-todo-ignore-timestamp to anything but nil (though due to the way the agenda code is written, it won’t harm – if this is set to t, Org does not even look at any other org-agenda-todo-ignore-* variables).
I submitted a patch to make these distinction more clear in the docstrings. We’ll see how it goes.
CategoryEnglish, CategoryBlog, CategoryEmacs, CategoryOrgMode