Doc fix for xterm-extra-capabilities

* lisp/term/xterm.el (xterm-extra-capabilities): Doc fix.

* etc/PROBLEMS: Mention xterm-extra-capabilities issue.

3 files changed, 28 insertions, 3 deletions

diff --git a/etc/PROBLEMS b/etc/PROBLEMS
index ae3f49868b2..939ce9f246d 100644
--- a/etc/PROBLEMS
+++ b/etc/PROBLEMS
@@ -1679,6 +1679,23 @@ recommended way of turning on Font-lock is by typing "M-x
 global-font-lock-mode RET" or by customizing the variable
 `global-font-lock-mode'.
 
+** Unexpected characters inserted into the buffer when you start Emacs.
+See eg http://debbugs.gnu.org/11129
+
+This can happen when you start Emacs in -nw mode in an Xterm.
+For example, in the *scratch* buffer, you might see something like:
+
+  0;276;0c
+
+This is more likely to happen if you are using Emacs over a slow
+connection, and begin typing before Emacs is ready to respond.
+
+This occurs when Emacs tries to query the terminal to see what
+capabilities it supports, and gets confused by the answer.
+To avoid it, set xterm-extra-capabilities to a value other than
+`check' (the default).  See that variable's documentation (in
+term/xterm.el) for more details.
+
 * Runtime problems specific to individual Unix variants
 
 ** GNU/Linux
diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index c505241e4c6..b6d33739e2a 100644
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,5 +1,7 @@
 2012-03-31  Glenn Morris  <rgm@gnu.org>
 
+        * term/xterm.el (xterm-extra-capabilities): Doc fix.
+
         * language/indian.el ("Devanagari"): Fix typo.  (Bug#11103)
 
         * calendar/calendar.el (calendar-window-list)
diff --git a/lisp/term/xterm.el b/lisp/term/xterm.el
index eea6d767512..7e56cd9fa1d 100644
--- a/lisp/term/xterm.el
+++ b/lisp/term/xterm.el
@@ -30,9 +30,15 @@
   :group 'emacs)
 
 (defcustom xterm-extra-capabilities 'check
-  "Set to a list if the XTerm supports modifyOtherKeys or
-reporting the background color.  Set to 'check to check for those
-features.  Set to nil to skip the checks."
+  "Whether Xterm supports some additional, more modern, features.
+If nil, just assume that it does not.
+If `check', try to check if it does.
+If a list, assume that the listed features are supported, without checking.
+
+The relevant features are:
+  modifyOtherKeys  -- if supported, more key bindings work (e.g, \"\\C-,\")
+  reportBackground -- if supported, Xterm reports its background color
+"
   :version "24.1"
   :group 'xterm
   :type '(choice (const :tag "No" nil)