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.

Lance

What does <kbd>F1</kbd><kbd>k</kbd><kbd>Shift</kbd>+<kbd>Tab</kbd> show? (or M-x describe-key S-Tab) – Sovereignty

Both return M-[ z (translated from M-[ Z) is undefined in the mini-buffer. – Lance

Hmm... I just ran into this in an 'emacsclient -nw' window in a GNU screen session. I used C-x C-c to detach the window to get back to the shell prompt (with emacs --daemon still running in the background). Then I opened a new emacslient window and S-tab worked fine. I re-attach the screen session from various terminals (gnome-terminal, xterm, cygwin mintty) depending on the platform I happen to be on. I can't say I tracked down the root cause, but opening a new 'emacsclient -nw' window "fixed" it in my case. emacs-24.5. Seems in my case to be a temporary key mapping mixup (not sure how) – Cierracig

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.

Dumah

We need an extra end-parend for the Emacs 23 code. Neither one seems to fix my issue. Emacs is still throwing the error with both of those lines in my .emacs file. – Lance

It is probably better to use [backtab] rather than [S-tab]. At least in Emacs 23, that seems to be the canonical name that S-tab, iso-left-tab and other variations are mapped to. – Responsiveness

@JSON: Thanks, indeed most modes have bindings for backtab now. @jrhorn424: do you still get exactly the same error message? What if you manually evaluate (define-key input-decode-map "\e[z" [backtab])? – Disinfect

Yes, I still receive the same exact error. Manually evaluating the expression returns [backtab] in the mini-buffer. Pressing S-TAB after evaluating the expression returns the same error I've been receiving. – Lance

I changed my OP to reflect the fact that Terminal.app appears to be the culprit. It doesn't explain why the key-remapping isn't sticking. – Lance

@jrhorn424: Strange... If you go to the *scratch* buffer any type (read-key-sequence "Type S-tab: ") then C-j and then S-tab at the prompt, what is inserted in the scratch buffer? Another test: if you start emacs in Terminal.app with TERM=xterm emacs -q -nw, what happens if you press S-tab? What is the value of $TERM in Terminal.app? – Disinfect

The *scratch* test (te-hehe) returns "^[[z" into the buffer. In the terminal, echo $TERM returns xterm-color. When starting emacs using TERM=xterm emacs -q -nw, S-tab works as expected. – Lance

According to this [Backtab Howto][1], ^[[z is a standard terminal sequence for backtab. I tried adding the lines from Step 3 to my .emacs to no avail. [1]: stuff.mit.edu/afs/sipb/user/daveg/Info/backtab-howto.txt – Lance

@jrhorn424: It seems that your terminal sends ESC [ Z, not ESC [ z. (That's the standard sequence by the way, as indicated in your reference.) Does it work if you use a capital Z in the Lisp code? – Disinfect

I'm using GNU emacs 22.1.1(I'm very new to emacs) and when I use this: (define-key function-key-map "\e[Z" [backtab]) I get this error: <backtab> is undefined. Any help? – Tropaeolin

@jonnyflash On what operating system? What if you use S-tab instead of backtab? – Disinfect

The main answer worked for me in Emacs 24.1.1: (add-hook 'term-setup-hook (lambda () (define-key input-decode-map "\e[Z" [backtab]))) – Aylmar

Answer 2

Like the original poster, I'm using Mac OS X, but version 10.6.8 and GNU Emacs 23.4.1. I was experiencing the same issues with S-Tab and org-mode. I was able to resolve this by following the steps that were extremely helpful at: http://stuff.mit.edu/afs/sipb/user/daveg/Info/backtab-howto.txt

Wardle

Please describe the steps instead of posting an URL – Spank