Document values of window-system and deprecate its use as predicate.

 src/frame.c (Fframep, Fwindow_system): Deprecate use as a predicate.
 Document all values.
 src/dispnew.c (syms_of_display) <initial-window-system, window-system>:
 Deprecate use as a boolean flag.  Document all values.
 src/display.texi (Window Systems): Deprecate use of window-system as
 a predicate.

2 files changed, 13 insertions, 0 deletions

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 2aca9fce5bf..ccbbe1b9c81 100644
--- a/doc/lispref/ChangeLog
+++ b/doc/lispref/ChangeLog
@@ -1,3 +1,8 @@
+2010-10-22  Eli Zaretskii  <eliz@gnu.org>
+
+        * display.texi (Window Systems): Deprecate use of window-system as
+        a predicate.
+
 2010-09-05  Alexander Klimov  <alserkli@inbox.ru>  (tiny change)
 
         * files.texi (Directory Names): Use \` rather than ^.
diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi
index 71680c56821..ba4cfca0854 100644
--- a/doc/lispref/display.texi
+++ b/doc/lispref/display.texi
@@ -5878,6 +5878,14 @@ selected frame).  The list of possible symbols it returns is the same
 one documented for the variable @code{window-system} above.
 @end defun
 
+  Do @emph{not} use @code{window-system} and
+@code{initial-window-system} as predicates or boolean flag variables,
+if you want to write code that works differently on text terminals and
+graphic displays.  That is because @code{window-system} is not a good
+indicator of Emacs capabilities on a given display type.  Instead, use
+@code{display-graphic-p} or any of the other @code{display-*-p}
+predicates described in @ref{Display Feature Testing}.
+
 @defvar window-setup-hook
 This variable is a normal hook which Emacs runs after handling the
 initialization files.  Emacs runs this hook after it has completed