org-agenda-todo
calls the org-todo
function interactively and in doing so, the it passes its own argument as it is to org-todo
1.
From C-h f org-todo
, you will get a complete understanding of what the values of ARG mean to org-todo
(and org-agenda-todo
):
org-todo is an interactive compiled Lisp function in `org.el'.
(org-todo &optional ARG)
Change the TODO state of an item.
The state of an item is given by a keyword at the start of the heading,
like
*** TODO Write paper
*** DONE Call mom
The different keywords are specified in the variable ‘org-todo-keywords’.
By default the available states are "TODO" and "DONE".
So for this example: when the item starts with TODO, it is changed to DONE.
When it starts with DONE, the DONE is removed. And when neither TODO nor
DONE are present, add TODO at the beginning of the heading.
With C-u prefix arg, use completion to determine the new state.
With numeric prefix arg, switch to that state.
With a double C-u prefix, switch to the next set of TODO keywords (nextset).
With a triple C-u prefix, circumvent any state blocking.
With a numeric prefix arg of 0, inhibit note taking for the change.
With a numeric prefix arg of -1, cancel repeater to allow marking as DONE.
When called through ELisp, arg is also interpreted in the following way:
‘none’ -> empty state
""(empty string) -> switch to empty state
‘done’ -> switch to DONE
‘nextset’ -> switch to the next set of keywords
‘previousset’ -> switch to the previous set of keywords
"WAITING" -> switch to the specified keyword, but only if it
really is a member of ‘org-todo-keywords’.
1 I learned the above by looking at the source code of org-agenda-todo
.
So it might be useful to email emacs-orgmode@gnu.org
with a request to add more information to the doc-string of org-agenda-todo
.. Something along the lines of "Refer to the documentation of org-todo
to learn how ARG is used.".