On Wed, 02 Nov 2011 19:11:38 -0400, Nick Dokos <nicholas.dokos@hp.com> wrote:
> They are generally called (somewhat misleadingly) diary sexps - they are
> executed by org-agenda-get-sexps (assuming that they are in some agenda
> file) when the agenda is constructed, once for every day displayed: they
> do their things and that's that. They are mostly used to remind one of
> birthdays, anniversaries etc, hence diary sexps.

Ah, okay. Thanks.

> > By the way: Is there a resource describing what special variables are
> > available to such functions (I only know about date) and how their
> > output should look like? I couldn't find anything in the org manual.
> > 
> 
> What do you mean by special variables? Any variable in the dynamic chain
> is fair game: date is available because a caller (org-agenda-list) goes
> to the trouble of binding it. Any other variable in this function or in
> any parent of org-agenda-get-sexps can be used (unless it's shadowed),
> but I'm not sure what use they would be.

I was just wondering if there is a listing of such variables specific to
org and explicitly intended to be used by diary sexps (i.e. not an
implementation detail that might change without warning).

> The function just has to return a string: the agenda code takes care
> of printing the result in the agenda.

Okay, I guess their simplicity explains why I couldn't find more
information on them in the manual.

> Diary sexps is probably the wrong thing to use for what you want: I
> don't know how far you want to take it, but iiuc, the easiest thing to
> do is write a script (in your favorite language) that generates a file
> of entries, say foo.org:
> 
> ,----
> | 
> | * notmuch threads
> | 
> | ** TODO check out this thread [[some link][thread title]]
> | ** TODO check out that thread [[some other link][other thread title]]
> | ...
> `----
> 
> Then open it in emacs and include it in your agenda with C-c [

Now that you mention it, this is a perfectly obvious solution. :)

By advising (there does not seem to be a hook for that) `org-todo-list'
I can even avoid running that script in a cronjob and thus not allowing
the agenda to become out of sync with the actual notmuch tags.

Thank you for your time and your answers.

Cheers,
Daniel