[This is a supplement to @TianshuWang's answer, primarily aiming to answer the OP's complaint that he could not find any examples with add-to-list
used to form a hierarchical, multi-level command structure. It's my attempt to explain how to get hold of an unfamiliar data structure. Hope it's helpful.]
org-agenda-custom-commands
is a list. Each element of it is a single custom command (another list). A custom command consists of a key
(a string), a description
(a string), a type
(one of a given set of symbols), a matcher
(a string which is supposed to be empty for many of the types, although it should be non-empty for some of them, e.g. tag searches where it specifies the tag to search for), a list of local settings, and a list of files (for exporting the agenda).
You can get this information from the doc string of the variable. Looking at examples helps but only if you take the trouble to map the example back to the documentation: that way you will understand the data structure and be able to understand an unfamiliar example or construct an example of your own.
Once you have this information ("It's a list"), then you know that you can construct the org-agenda-custom-commands
list like any other list: you can set it to a given list of elements (the elements are custom commands in this case):
(setq org-agenda-custom-commands '(elt elt ... ))
OR you can add an element to a preexisting list:
(add-to-list 'org-agenda-custom-commands elt)
Just like any other list.
The only thing that's special to org-agenda-custom-commands
is that its elements are custom commands, i.e. lists of a specific form as described above.
Now the doc string also describes a special case where you can group a bunch of commands under a prefix key. And that adds another wrinkle to what can be considered an element of the list. But once you understand that this is acceptable, then you know how to add it to the list: the same way as before.
You say that you could not find an example with add-to-list
: so what? The number of programs that can be written is infinite, so it is hardly
surprising that you cannot find an explicit example of each. The point is that you need to get an understanding of the language and the data structures it supports beyond just being able to copy an existing example.
And you also need to read the docs carefully: there is an example of a hierarchical org-agenda-custom-commands
in the variable's doc string: all you have to do is C-h v org-agenda-custom-commands
. It says:
When using several characters as key to a command, the first characters are prefix commands. For the dispatcher to display useful information, you should provide a description for the prefix, like
(setq org-agenda-custom-commands
'(("h" . "HOME + Name tag searches") ; describe prefix "h"
("hl" tags "+HOME+Lisa")
("hp" tags "+HOME+Peter")
("hk" tags "+HOME+Kim")))
It shows you an example of the list constructed by listing its four elements. But you know it's a list, so you know you can also construct it by adding one element at a time with add-to-list
(as in @TianshuWang's answer).
The problem of course is that at first, all you see is a meaningless jumble of symbols and parentheses and you don't know how to get hold of this thing: but you know it's a list so you just have to step back and forget about the details and look at it as a list of elements; once you can identify the individual elements (which may themselves be pretty complicated) then you can look at each element in turn, until you have comprehended the structure all the way down.
So don't get lost in the details and don't waste your time looking for examples all over the internet: look at the structure and think about it. After you've done that in a dozen simple and not-so-simple cases, you'll get the knack of it. Inevitably, there will be times when things seem too complicated. Then you ask a question, but when you get an answer, you should go back and ask yourself: in the light of the answer, how could I have figured it out myself? Then next time, you'll have a better chance of doing exactly that.