Re: display-buffer vs. current-buffer vs. post-command-hook

[martin rudalics]

> I'm sorry but I don't understand your statement.  Should there not be an
> expectation that (current-buffer)'s return value does not change between
> the second and third call in my original snippet?

No.  The primary concern is that the current buffer must not be changed
by `describe-key' or any other function that uses a temporary buffer to
display its results.

> Put another way, under what circumstances should one expect
> current-buffer's return value to be stable in user-written elisp?

The current buffer should never be changed by any function, unless it is
a purpose of that function to change the current buffer.

> Put a third way, what about describe-keys documentation should lead an
> elisp author to understand that current-buffer will not reflect its effect
> until after a [run-at-time 0]?
> (sorry for the barrage of questions; I feel there's a fundamental something
> I'm missing in play here and trying to see if you know what it is :))

I suppose you missed the following aspect described in section 26.2 of
the Elisp manual entitled "The Current Buffer":

  When an editing command returns to the editor command loop, Emacs
  automatically calls `set-buffer' on the buffer shown in the selected
  window.

[run-at-time 0] clearly runs after that.

martin