master fda07b56d9e 2/2: Revise selection documentation

[Po Lu]

branch: master
commit fda07b56d9e985b6ae74a6845453b55da0345e3c
Author: Po Lu <luangruo@yahoo.com>
Commit: Po Lu <luangruo@yahoo.com>

    Revise selection documentation
    
    * doc/lispref/frames.texi (Window System Selections):
    (X Selections):
    
    * lisp/select.el (selection-coding-system): Correct
    misunderstandings about the nature of selection-coding-system
    under X.
---
 doc/lispref/frames.texi | 27 ++++++++++++++-------------
 lisp/select.el          | 39 ++++++++++++++++++++-------------------
 2 files changed, 34 insertions(+), 32 deletions(-)

diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi
index 1a7af04b103..ef5ed146015 100644
--- a/doc/lispref/frames.texi
+++ b/doc/lispref/frames.texi
@@ -4058,11 +4058,12 @@ is used to encode selection data, and takes effect on 
MS-DOS,
 MS-Windows and X@.
 
 Under MS-DOS and MS-Windows, it is the coding system by which all
-clipboard text will be encoded and decoded, whereas on X it merely
-supplies the EOL format of the selection text sent in response to a
-request for text encoded by a matching coding system; which is to say
-that if its value is @code{utf-8-dos}, it will influence requests for
-@code{UTF8_STRING} data, but not those for @code{STRING}.
+non-ASCII clipboard text will be encoded and decoded; if set under X,
+it provides the coding system calls to @code{gui-get-selection} will
+decode selection data for a subset of text data types by, and also
+forces replies to selection requests for the polymorphic @code{TEXT}
+data type to be encoded by the @code{compound-text-with-extensions}
+coding system rather than Unicode.
 
 Its default value is the system code page under MS-Windows 95, 98 or
 Me, @code{utf-16le-dos} under NT/W2K/XP, @code{iso-latin-1-dos} on
@@ -4154,12 +4155,12 @@ format and data type to convert the data transferred by 
the selection
 owner to a Lisp representation, which @code{gui-get-selection}
 returns.
 
-  By default, Emacs converts selection data consisting of any series
-of bytes to a unibyte string holding those bytes, that consisting of a
-single 16-bit or 32-bit word as an unsigned number, and that
-consisting of multiple such words as a vector of unsigned numbers.
-However, Emacs applies special treatment for data from the following
-conversion targets:
+  Emacs converts selection data consisting of any series of bytes to a
+unibyte string holding those bytes, that consisting of a single 16-bit
+or 32-bit word as an unsigned number, and that consisting of multiple
+such words as a vector of unsigned numbers.  The exceptions to this
+general pattern are that Emacs applies special treatment for data from
+the following conversion targets:
 
 @table @code
 @item INTEGER
@@ -4384,8 +4385,8 @@ This selection converter returns selection data as:
 @itemize @bullet
 @item
 A string of type @code{C_STRING}, if the selection contents contain no
-multibyte characters, or contains 8-bit characters with all 8 bits
-set.
+multibyte characters, or contain ``raw 8-bit bytes'' (@pxref{Text
+Representations}).
 
 @item
 A string of type @code{STRING}, if the selection contents can be
diff --git a/lisp/select.el b/lisp/select.el
index 09c678867d0..f62f7b07239 100644
--- a/lisp/select.el
+++ b/lisp/select.el
@@ -49,27 +49,28 @@ the current system default encoding on 9x/Me, `utf-16le-dos'
 \(Unicode) on NT/W2K/XP, and `iso-latin-1-dos' on MS-DOS.
 
 For X Windows:
-When sending text via selection and clipboard, if the target
-data-type matches this coding system according to the table
-below, it is used for encoding the text.  Otherwise (including
-the case that this variable is nil), a proper coding system is
-selected as below:
-
-data-type      coding system
----------      -------------
-UTF8_STRING    utf-8
-COMPOUND_TEXT  compound-text-with-extensions
-STRING         iso-latin-1
-C_STRING       raw-text-unix
-
-When receiving text, if this coding system is non-nil, it is used
-for decoding regardless of the data-type.  If this is nil, a
-proper coding system is used according to the data-type as above.
 
-See also the documentation of the variable `x-select-request-type' how
-to control which data-type to request for receiving text.
+This coding system replaces that of the default coding system
+selection text is encoded by in reaction to a request for the
+polymorphic `TEXT' selection target when its base coding system
+is compatible with `compound-text' and the text being encoded
+cannot be rendered Latin-1 without loss of information.
+
+It also replaces the coding system by which calls to
+`gui-get-selection' decode selection requests for text data
+types, which are enumerated below beside their respective coding
+systems otherwise used.
+
+DATA TYPE                      CODING SYSTEM
+--------------------------     -------------
+UTF8_STRING                    utf-8
+text/plain\\;charset=utf-8     utf-8
+COMPOUND_TEXT                  compound-text-with-extensions
+STRING                         iso-latin-1
+C_STRING                       raw-text-unix
 
-The default value is nil."
+See also the documentation of the variable `x-select-request-type' how
+to control which data-type to request for receiving text."
   :type 'coding-system
   :group 'mule
   ;; Default was compound-text-with-extensions in 22.x (pre-unicode).