; Improve documentation of 'gui-get-selection' use on X

* doc/lispref/frames.texi (Window System Selections):
* lisp/select.el (gui-get-selection): Suggest to use an explicit
DATA-TYPE when calling 'gui-get-selection'.

(cherry picked from commit 01c03043e6e93dd12570a960ca54108d543578db)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 32d6ffc48ed0a6672517e04b608ee48da00d13d3..8c843952c2967c24ba3a58abdb6f095a5463663a 100644 (file)
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -4161,8 +4161,14 @@ programs.  It takes two optional arguments, @var{type} and
 
 The @var{data-type} argument specifies the form of data conversion to
 use, to convert the raw data obtained from another program into Lisp
-data.  @xref{X Selections}, for an enumeration of data types valid under
-X, and @pxref{Other Selections} for those elsewhere.
+data.  It defaults to @code{STRING}.  @xref{X Selections}, for an
+enumeration of data types valid on X, and @pxref{Other Selections} for
+those elsewhere.  On X Window system, we recommend to always specify a
+particular @var{data-type}, especially if the selection is expected to
+be non-ASCII text (in which case Lisp programs should prefer
+@code{UTF8_STRING} as the value of @var{data-type}).  This is because
+the default @var{data-type} value, @code{STRING}, can only support
+Latin-1 text, which in many cases is nowadays inadequate.
 @end defun
 
 @defopt selection-coding-system

diff --git a/lisp/select.el b/lisp/select.el
index d8e97f33001a2c19f8213ecef5fedf1bf7c9b29c..59eedc79263d025c03ba9f8addf2b4bdc9c3aa61 100644 (file)
--- a/lisp/select.el
+++ b/lisp/select.el
@@ -372,10 +372,15 @@ all upper-case names.  The most often used ones, in addition to
 `PRIMARY', are `SECONDARY' and `CLIPBOARD'.
 
 DATA-TYPE is usually `STRING', but can also be one of the symbols
-in `selection-converter-alist', which see.  Window systems other
-than X usually support only a small subset of these symbols, in
-addition to `STRING'; MS-Windows supports `TARGETS', which reports
-the formats available in the clipboard if TYPE is `CLIPBOARD'."
+in `selection-converter-alist', which see.  On X, we recommend
+to always use a specific DATA-TYPE expected from the selection
+owner.  In particular, if the data is expected to be non-ASCII
+text, in many cases using \\='UTF8_STRING is the most reasonable
+value for DATA-TYPE.
+
+Window systems other than X usually support only a small subset of
+these symbols, in addition to `STRING'; MS-Windows supports `TARGETS',
+which reports the formats available in the clipboard if TYPE is `CLIPBOARD'."
   (let ((data (gui-backend-get-selection (or type 'PRIMARY)
                                          (or data-type 'STRING))))
     (when (and (stringp data)