From cf0d8ecbfa072faad7d1a210a0e6d18263e23028 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 15 Mar 2025 11:48:36 +0200 Subject: [PATCH] ; 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) --- doc/lispref/frames.texi | 10 ++++++++-- lisp/select.el | 13 +++++++++---- 2 files changed, 17 insertions(+), 6 deletions(-) diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 32d6ffc48ed..8c843952c29 100644 --- 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 d8e97f33001..59eedc79263 100644 --- 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) -- 2.39.5