Fix Bug#3888:

w32-vars.el (x-select-enable-clipboard): Doc fix.
term/pc-win.el (x-display-name, x-colors)
(x-select-enable-clipboard, x-select-text): Doc fix.
term/common-win.el (x-display-name, x-colors): Doc fix.
term/ns-win.el (x-select-text, x-setup-function-keys, x-colors)
(xw-defined-colors): Doc fix.
w32-fns.el (x-select-text, x-setup-function-keys)
(x-get-selection, x-set-selection): Doc fix.
term/x-win.el (x-select-text, x-setup-function-keys)
(x-select-enable-clipboard, xw-defined-colors): Doc fix.
select.el (x-set-selection): Doc fix.

4 files changed, 71 insertions, 21 deletions

diff --git a/lisp/term/common-win.el b/lisp/term/common-win.el
index 5764dbc8dc..f706dba858 100644
--- a/lisp/term/common-win.el
+++ b/lisp/term/common-win.el
@@ -131,7 +131,9 @@
 				  initial-frame-alist)))
 
 (defvar x-display-name nil
-  "The name of the X display on which Emacs was started.
+  "The name of the window display on which Emacs was started.
+On X, the display name of individual X frames is recorded in the
+`display' frame parameter.")
 
 For the X display name of individual frames, see the `display'
 frame parameter.")
@@ -288,8 +290,10 @@ This function returns ARGS minus the arguments that have been processed."
     "cyan" "medium spring green" "spring green" "green" "lawn green" "chartreuse"
     "yellow" "gold" "orange" "dark orange" "orange red" "red" "white" "white smoke"
     "gainsboro" "light grey" "gray" "dark grey" "dim gray" "black" )
-  "The list of X colors from the `rgb.txt' file.
-XConsortium: rgb.txt,v 10.41 94/02/20 18:39:36 rws Exp")
+  "List of basic colors available on color displays.
+For X, the list comes from the `rgb.txt' file,v 10.41 94/02/20.
+For Nextstep, this is a list of non-PANTONE colors returned by
+the operating system.")
 
 ;; arch-tag: 2a128601-99cc-401e-9dff-0ee6a36102ef
 ;;; common-win.el ends here
diff --git a/lisp/term/ns-win.el b/lisp/term/ns-win.el
index 5830f438cc..ad026e6fd0 100644
--- a/lisp/term/ns-win.el
+++ b/lisp/term/ns-win.el
@@ -309,7 +309,7 @@ The properties returned may include `top', `left', `height', and `width'."
 (defalias 'do-applescript 'ns-do-applescript)
 
 (defun x-setup-function-keys (frame)
-  "Set up function Keys for Nextstep for frame FRAME."
+  "Set up function keys on the graphical frame FRAME."
   (unless (terminal-parameter frame 'x-setup-function-keys)
     (with-selected-frame frame
       (setq interprogram-cut-function 'x-select-text
@@ -1003,7 +1003,19 @@ See the documentation of `create-fontset-from-fontset-spec' for the format.")
 (defvar ns-last-selected-text nil)
 
 (defun x-select-text (text &optional push)
-  "Put TEXT, a string, on the pasteboard."
+  "Select TEXT, a string, according to the window system.
+
+On X, put TEXT in the primary X selection.  For backward
+compatibility with older X applications, set the value of X cut
+buffer 0 as well, and if the optional argument PUSH is non-nil,
+rotate the cut buffers.  If `x-select-enable-clipboard' is
+non-nil, copy the text to the X clipboard as well.
+
+On Windows, make TEXT the current selection.  If
+`x-select-enable-clipboard' is non-nil, copy the text to the
+clipboard as well.  The argument PUSH is ignored.
+
+On Nextstep, put TEXT in the pasteboard; PUSH is ignored."
   ;; Don't send the pasteboard too much text.
   ;; It becomes slow, and if really big it causes errors.
   (ns-set-pasteboard text)
@@ -1113,12 +1125,13 @@ See the documentation of `create-fontset-from-fontset-spec' for the format.")
 (declare-function ns-list-colors "nsfns.m" (&optional frame))
 
 (defvar x-colors (ns-list-colors)
-  "The list of colors defined in non-PANTONE color files.")
+  "List of basic colors available on color displays.
+For X, the list comes from the `rgb.txt' file,v 10.41 94/02/20.
+For Nextstep, this is a list of non-PANTONE colors returned by
+the operating system.")
 
 (defun xw-defined-colors (&optional frame)
-  "Return a list of colors supported for a particular frame.
-The argument FRAME specifies which frame to try.
-The value may be different for frames on different Nextstep displays."
+  "Internal function called by `defined-colors'."
   (or frame (setq frame (selected-frame)))
   (let ((all-colors x-colors)
 	(this-color nil)
diff --git a/lisp/term/pc-win.el b/lisp/term/pc-win.el
index 332e151a86..985cbfb671 100644
--- a/lisp/term/pc-win.el
+++ b/lisp/term/pc-win.el
@@ -181,9 +181,14 @@ created."
 
 ;; From lisp/term/x-win.el
 (defvar x-display-name "pc"
-  "The display name specifying the MS-DOS display and frame type.")
+  "The name of the window display on which Emacs was started.
+On X, the display name of individual X frames is recorded in the
+`display' frame parameter.")
 (defvar x-colors (mapcar 'car msdos-color-values)
-  "The list of colors available on a PC display under MS-DOS.")
+  "List of basic colors available on color displays.
+For X, the list comes from the `rgb.txt' file,v 10.41 94/02/20.
+For Nextstep, this is a list of non-PANTONE colors returned by
+the operating system.")
 
 ;; From lisp/term/w32-win.el
 ;
@@ -196,12 +201,28 @@ created."
 
 (defcustom x-select-enable-clipboard t
   "Non-nil means cutting and pasting uses the clipboard.
-This is the default on this system, since MS-Windows does not
-support other types of selections."
+This is in addition to, but in preference to, the primary selection.
+
+On MS-Windows, this is non-nil by default, since Windows does not
+support other types of selections.  \(The primary selection that is
+set by Emacs is not accessible to other programs on Windows.\)"
   :type 'boolean
   :group 'killing)
 
 (defun x-select-text (text &optional push)
+  "Select TEXT, a string, according to the window system.
+
+On X, put TEXT in the primary X selection.  For backward
+compatibility with older X applications, set the value of X cut
+buffer 0 as well, and if the optional argument PUSH is non-nil,
+rotate the cut buffers.  If `x-select-enable-clipboard' is
+non-nil, copy the text to the X clipboard as well.
+
+On Windows, make TEXT the current selection.  If
+`x-select-enable-clipboard' is non-nil, copy the text to the
+clipboard as well.  The argument PUSH is ignored.
+
+On Nextstep, put TEXT in the pasteboard; PUSH is ignored."
   (if x-select-enable-clipboard
       (w16-set-clipboard-data text))
   (setq x-last-selected-text text))
diff --git a/lisp/term/x-win.el b/lisp/term/x-win.el
index 3e00a81be1..17c0f3aef9 100644
--- a/lisp/term/x-win.el
+++ b/lisp/term/x-win.el
@@ -255,7 +255,7 @@ exists."
 (defvar x-colors)
 
 (defun xw-defined-colors (&optional frame)
-  "Internal function called by `defined-colors', which see."
+  "Internal function called by `defined-colors'."
   (or frame (setq frame (selected-frame)))
   (let ((all-colors x-colors)
 	(this-color nil)
@@ -292,7 +292,7 @@ exists."
   "Keymap of possible alternative meanings for some keys.")
 
 (defun x-setup-function-keys (frame)
-  "Set up `function-key-map' on FRAME for the X window system."
+  "Set up `function-key-map' on the graphical frame FRAME."
   ;; Don't do this twice on the same display, or it would break
   ;; normal-erase-is-backspace-mode.
   (unless (terminal-parameter frame 'x-setup-function-keys)
@@ -1239,7 +1239,11 @@ It is said that overlarge strings are slow to put into the cut buffer.")
 
 (defcustom x-select-enable-clipboard nil
   "Non-nil means cutting and pasting uses the clipboard.
-This is in addition to, but in preference to, the primary selection."
+This is in addition to, but in preference to, the primary selection.
+
+On MS-Windows, this is non-nil by default, since Windows does not
+support other types of selections.  \(The primary selection that is
+set by Emacs is not accessible to other programs on Windows.\)"
   :type 'boolean
   :group 'killing)
 
@@ -1249,11 +1253,19 @@ This is in addition to, but in preference to, the primary selection."
   :group 'killing)
 
 (defun x-select-text (text &optional push)
-  "Make TEXT, a string, the primary X selection.
-Also, set the value of X cut buffer 0, for backward compatibility
-with older X applications.
[email protected] says it's not desirable to put kills
-in the clipboard."
+  "Select TEXT, a string, according to the window system.
+
+On X, put TEXT in the primary X selection.  For backward
+compatibility with older X applications, set the value of X cut
+buffer 0 as well, and if the optional argument PUSH is non-nil,
+rotate the cut buffers.  If `x-select-enable-clipboard' is
+non-nil, copy the text to the X clipboard as well.
+
+On Windows, make TEXT the current selection.  If
+`x-select-enable-clipboard' is non-nil, copy the text to the
+clipboard as well.  The argument PUSH is ignored.
+
+On Nextstep, put TEXT in the pasteboard; PUSH is ignored."
   ;; With multi-tty, this function may be called from a tty frame.
   (when (eq (framep (selected-frame)) 'x)
     ;; Don't send the cut buffer too much text.