Clarify UTF8_STRING handling. [Bug 1778563]

1 files changed, 18 insertions, 13 deletions

diff --git a/doc/selection.n b/doc/selection.n
index 80e8031..af2072b 100644
--- a/doc/selection.n
+++ b/doc/selection.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: selection.n,v 1.10 2007/10/29 16:04:14 dkf Exp $
+'\" RCS: @(#) $Id: selection.n,v 1.11 2007/10/30 15:20:21 dkf Exp $
 '\" 
 .so man.macros
 .TH selection n 8.1 Tk "Tk Built-In Commands"
@@ -54,22 +54,27 @@ should be an atom name such as STRING or FILE_NAME; see the
 Inter-Client Communication Conventions Manual for complete details.
 \fIType\fR defaults to STRING.  The selection owner may choose to
 return the selection in any of several different representation
-formats, such as STRING, ATOM, INTEGER, etc. (this format is different
+formats, such as STRING, UTF8_STRING, ATOM, INTEGER, etc. (this format
+is different
 than the selection type; see the ICCCM for all the confusing details).
 If the selection is returned in a non-string format, such as INTEGER
 or ATOM, the \fBselection\fR command converts it to string format as a
 collection of fields separated by spaces: atoms are converted to their
 textual names, and anything else is converted to hexadecimal integers.
+Note that \fBselection get\fR does not retrieve the selection in the
+UTF8_STRING format unless told to.
 .TP
-\fBselection handle\fR ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR? ?\fB\-format\fR \fIformat\fR? \fIwindow command\fR
+\fBselection handle\fR ?\fB\-selection\fR \fIs\fR? ?\fB\-type\fR \fIt\fR? ?\fB\-format\fR \fIf\fR? \fIwindow command\fR
 Creates a handler for selection requests, such that \fIcommand\fR will
-be executed whenever \fIselection\fR is owned by \fIwindow\fR and
-someone attempts to retrieve it in the form given by \fItype\fR
-(e.g. \fItype\fR is specified in the \fBselection get\fR command).
-\fISelection\fR defaults to PRIMARY, \fItype\fR defaults to STRING, and
-\fIformat\fR defaults to STRING.  If \fIcommand\fR is an empty string
-then any existing handler for \fIwindow\fR, \fItype\fR, and
-\fIselection\fR is removed.
+be executed whenever selection \fIs\fR is owned by \fIwindow\fR and
+someone attempts to retrieve it in the form given by type \fIt\fR
+(e.g. \fIt\fR is specified in the \fBselection get\fR command).
+\fIS\fR defaults to PRIMARY, \fIt\fR defaults to STRING, and
+\fIf\fR defaults to STRING.  If \fIcommand\fR is an empty string
+then any existing handler for \fIwindow\fR, \fIt\fR, and
+\fIs\fR is removed.
+Note that when the selection is handled as type STRING it is also
+automatically handled as type UTF8_STRING as well.
 .RS
 .PP
 When \fIselection\fR is requested, \fIwindow\fR is the selection owner,
@@ -98,7 +103,9 @@ The \fIformat\fR argument specifies the representation that should be
 used to transmit the selection to the requester (the second column of
 Table 2 of the ICCCM), and defaults to STRING.  If \fIformat\fR is
 STRING, the selection is transmitted as 8-bit ASCII characters (i.e.
-just in the form returned by \fIcommand\fR).  If \fIformat\fR is
+just in the form returned by \fIcommand\fR, in the system \fBencoding\fR;
+the UTF8_STRING format always uses UTF-8 as its encoding).
+If \fIformat\fR is
 ATOM, then the return value from \fIcommand\fR is divided into fields
 separated by white space;  each field is converted to its atom value,
 and the 32-bit atom value is transmitted instead of the atom name.
@@ -165,9 +172,7 @@ proc lost {} {
    puts "Lost selection"
 }
 .CE
-
 .SH "SEE ALSO"
 clipboard(n)
-
 .SH KEYWORDS
 clear, format, handler, ICCCM, own, selection, target, type