something confusing about define-key (and the issue of when to quote an argument)

Question

It seems one is not supposed to quote KEYMAP when using define-key.

(define-key org-remember-mode-map "\C-c\C-r" 'org-remember-kill)

I'm confused because I think that all arguments of a function that is not quoted are evaluated, and according to the help, define-key is a function, not a macro. I don't see why the value of KEYMAP can be modified after a call of define-key.

(defun increment-value (a)
  (setq a (+ 1 a)))

(setq my-num 10)

(increment-value my-num)

my-num ; ===> 10

Answer 1

you're confusing value and name-value mapping.

in your increment-value function, you're not changing a's value as much as changing the mapping of the name a to a new value.

Fundamentally, there is no way to change the value of 10. 10 is 10!

But in the first case, you can either modify the mapping of the name org-remember-mode-map to a fully different map (set a new value), or you can alter the map pointed by that name (its current value). This is what define-key does.

Illustration:

(setq a '(1 2)) -> (1 2)
(setcar a 4) -> 4
a -> (4 2)

Answer 2

Everything you write is completely correct. The thing you are missing is that lists (keymaps are represented as lists) are not values themselves, but containers of values. Thus, you can pass a list to a function and have that function change the values of the list, but the list you have is still the same list.

All the details are in the Cons Cell Type section of the elisp manual.

Answer 3

You aren't actually changing what 'org-remember-map is (a pointer to a particular list structure), you are modifying the actual structure. Read this info page for details on modifying lists.

Specificially, if you take a look at the documentation for 'make-keymap:

(make-keymap &optional string)

Construct and return a new keymap, of the form (keymap CHARTABLE . ALIST). CHARTABLE is a char-table that holds the bindings for all characters without modifiers. All entries in it are initially nil, meaning "command undefined". ALIST is an assoc-list which holds bindings for function keys, mouse events, and any other things that appear in the input stream. Initially, ALIST is nil.

You'll see that keymap is a list with three elements. Let me draw that for you (yay M-x artist-mode):

 org-remember-map
    |
    |
    v
 +----+----+    +----+----+
 | |  |  --+--->+  / | \  |
 +-+--+----+    +-/--+--\-+
   |              |     |
   v              v     v
keymap      CHARTABLE  ALIST

So, the value of the 'org-remember-map is something like the above structure, and when you define a key, what you are doing is changing what is pointed to in the ALIST blob part of the structure.