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.

diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog
index 2aca9fce5bf5c2bfa2c142392b3edd28757326c8..ccbbe1b9c81dce4677cebe13e177bccf89537c08 100644 (file)
--- 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 71680c56821bb0b03c72c756adef5a1386a74fda..ba4cfca0854d58ea65684952af8c4e10465dad7f 100644 (file)
--- 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

diff --git a/src/ChangeLog b/src/ChangeLog
index d33f9dd4f0b0948e563415f0ccd70e76e0a2c4e2..d8e0727b81b78520ccaa7c9e5a8c13e0c763e315 100644 (file)
--- a/src/ChangeLog
+++ b/src/ChangeLog
@@ -1,3 +1,10 @@
+2010-10-22  Eli Zaretskii  <eliz@gnu.org>
+
+       * frame.c (Fframep, Fwindow_system): Deprecate use as a predicate.
+
+       * dispnew.c (syms_of_display) <initial-window-system, window-system>:
+       Deprecate use as a boolean flag.
+
 2010-10-18  Ken Brown  <kbrown@cornell.edu>
 
        * s/cygwin.h (SIGNALS_VIA_CHARACTERS): New define (bug#7225).

diff --git a/src/dispnew.c b/src/dispnew.c
index d32ce48cce6a190619ee1a2b1cccac864daba3cf..b6149057a5a6dc0f89a3cefcdd92a1763f1d97be 100644 (file)
--- a/src/dispnew.c
+++ b/src/dispnew.c
@@ -7141,13 +7141,29 @@ It is up to you to set this variable if your terminal can do that.  */);
 
   DEFVAR_LISP ("initial-window-system", &Vinitial_window_system,
               doc: /* Name of the window system that Emacs uses for the first frame.
-The value is a symbol--for instance, `x' for X windows.
-The value is nil if Emacs is using a text-only terminal.  */);
+The value is a symbol:
+ nil for a termcap frame (a character-only terminal),
+ 'x' for an Emacs frame that is really an X window,
+ 'w32' for an Emacs frame that is a window on MS-Windows display,
+ 'ns' for an Emacs frame on a GNUstep or Macintosh Cocoa display,
+ 'pc' for a direct-write MS-DOS frame.
+
+Use of this variable as a boolean is deprecated.  Instead,
+use `display-graphic-p' or any of the other `display-*-p'
+predicates which report frame's specific UI-related capabilities.  */);
 
   DEFVAR_KBOARD ("window-system", Vwindow_system,
                 doc: /* Name of window system through which the selected frame is displayed.
-The value is a symbol--for instance, `x' for X windows.
-The value is nil if the selected frame is on a text-only-terminal.  */);
+The value is a symbol:
+ nil for a termcap frame (a character-only terminal),
+ 'x' for an Emacs frame that is really an X window,
+ 'w32' for an Emacs frame that is a window on MS-Windows display,
+ 'ns' for an Emacs frame on a GNUstep or Macintosh Cocoa display,
+ 'pc' for a direct-write MS-DOS frame.
+
+Use of this variable as a boolean is deprecated.  Instead,
+use `display-graphic-p' or any of the other `display-*-p'
+predicates which report frame's specific UI-related capabilities.  */);
 
   DEFVAR_LISP ("window-system-version", &Vwindow_system_version,
               doc: /* The version number of the window system in use.

diff --git a/src/frame.c b/src/frame.c
index a30d1e18175a1234c08da6920c39ad22ab1d8619..d9106a721a95c5012343716d55774afc09d53684 100644 (file)
--- a/src/frame.c
+++ b/src/frame.c
@@ -211,11 +211,12 @@ extern Lisp_Object QCname, Qfont_param;
 \f
 DEFUN ("framep", Fframep, Sframep, 1, 1, 0,
        doc: /* Return non-nil if OBJECT is a frame.
-Value is t for a termcap frame (a character-only terminal),
-`x' for an Emacs frame that is really an X window,
-`w32' for an Emacs frame that is a window on MS-Windows display,
-`ns' for an Emacs frame on a GNUstep or Macintosh Cocoa display,
-`pc' for a direct-write MS-DOS frame.
+Value is:
+  t for a termcap frame (a character-only terminal),
+ 'x' for an Emacs frame that is really an X window,
+ 'w32' for an Emacs frame that is a window on MS-Windows display,
+ 'ns' for an Emacs frame on a GNUstep or Macintosh Cocoa display,
+ 'pc' for a direct-write MS-DOS frame.
 See also `frame-live-p'.  */)
      (object)
      Lisp_Object object;
@@ -259,8 +260,18 @@ return values.  */)
 
 DEFUN ("window-system", Fwindow_system, Swindow_system, 0, 1, 0,
        doc: /* The name of the window system that FRAME is displaying through.
-The value is a symbol---for instance, 'x' for X windows.
-The value is nil if Emacs is using a text-only terminal.
+The value is a symbol:
+ nil for a termcap frame (a character-only terminal),
+ 'x' for an Emacs frame that is really an X window,
+ 'w32' for an Emacs frame that is a window on MS-Windows display,
+ 'ns' for an Emacs frame on a GNUstep or Macintosh Cocoa display,
+ 'pc' for a direct-write MS-DOS frame.
+
+FRAME defaults to the currently selected frame.
+
+Use of this function as a predicate is deprecated.  Instead,
+use `display-graphic-p' or any of the other `display-*-p'
+predicates which report frame's specific UI-related capabilities.  */)
 
 FRAME defaults to the currently selected frame.  */)
   (frame)