Shift-Tab produces cryptic error in Emacs

Question

I'm trying to learn org-mode and noticed my files are folded neatly when I exit emacs. When pressing S-TAB in an attempt to unfold the entire file, I get the following error message in the mini-buffer: M-[ z is undefined. Googling the error wasn't helpful. Any idea where the hiccup is occurring and how I might fix it?

I'm using Mac OS X 10.6.4 with Terminal.app, GNU Emacs 23.2.1.

Edit: I can confirm now that the problem is Terminal.app. I do not receive this error message using Carbon Emacs or when using Emacs from within iTerm.app.

Thanks to Gilles for patiently walking me through a solution.

Answer 1

The interface between the terminal and the program running inside it (here, Emacs) can only send characters, not keys. So special keys or key combinations often send a key sequence beginning with ESC. For example, your terminal apparently sends ESC [ Z for Shift+Tab.

Normally Emacs translates these character sequences back into key names, but it seems that the developers missed this one. You can define it yourself with

(add-hook 'term-setup-hook
          (lambda () (define-key input-decode-map "\e[Z" [backtab])))

(For Emacs <= 22, just use (define-key function-key-map "\e[Z" [backtab]).)

Some modes may define bindings for S-tab and not backtab. If you have Emacs 23, (define-key function-key-map [S-tab] [backtab]) should make these modes work.