1 files changed, 28 insertions, 20 deletions
diff --git a/doc/selection.n b/doc/selection.n
index dcf12b2..8aee321 100644
--- a/doc/selection.n
+++ b/doc/selection.n
@@ -35,35 +35,44 @@ so that no window owns the selection anymore.  \fISelection\fR
 specifies the X selection that should be cleared, and should be an
 atom name such as PRIMARY or CLIPBOARD; see the Inter-Client
 Communication Conventions Manual for complete details.
-\fISelection\fR defaults to PRIMARY and \fIwindow\fR defaults to ``.''.
+\fISelection\fR defaults to PRIMARY and \fIwindow\fR defaults to
+.QW . .
 Returns an empty string. 
 .TP
 \fBselection get\fR ?\fB\-displayof\fR \fIwindow\fR? ?\fB\-selection\fR \fIselection\fR? ?\fB\-type\fR \fItype\fR?
 Retrieves the value of \fIselection\fR from \fIwindow\fR's display and
 returns it as a result.  \fISelection\fR defaults to PRIMARY and
-\fIwindow\fR defaults to ``.''. 
+\fIwindow\fR defaults to
+.QW . .
 \fIType\fR specifies the form in which the selection is to be returned
-(the desired ``target'' for conversion, in ICCCM terminology), and
+(the desired
+.QW target
+for conversion, in ICCCM terminology), and
 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,
@@ -71,7 +80,6 @@ and \fItype\fR is the requested type, \fIcommand\fR will be executed
 as a Tcl command with two additional numbers appended to it
 (with space separators).  
 The two additional numbers
-.VS
 are \fIoffset\fR and \fImaxChars\fR:  \fIoffset\fR specifies a starting
 character position in the selection and \fImaxChars\fR gives the maximum
 number of characters to retrieve.  The command should return a value consisting
@@ -85,16 +93,17 @@ include all of the remainder of the selection;  if the length of
 \fIcommand\fR will be invoked again, until it eventually
 returns a result shorter than \fImaxChars\fR.  The value of \fImaxChars\fR
 will always be relatively large (thousands of characters).
-.VE
 .PP
 If \fIcommand\fR returns an error then the selection retrieval is rejected
-just as if the selection didn't exist at all.
+just as if the selection did not exist at all.
 .PP
 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.
@@ -104,7 +113,7 @@ converted to a 32-bit integer;  an array of integers is transmitted
 to the selection requester.
 .PP
 The \fIformat\fR argument is needed only for compatibility with
-selection requesters that don't use Tk.  If Tk is being
+selection requesters that do not use Tk.  If Tk is being
 used to retrieve the selection then the value is converted back to
 a string at the requesting end, so \fIformat\fR is
 irrelevant.
@@ -117,7 +126,8 @@ The first form of \fBselection own\fR returns the path name of the
 window in this application that owns \fIselection\fR on the display
 containing \fIwindow\fR, or an empty string if no window in this
 application owns the selection.  \fISelection\fR defaults to PRIMARY and
-\fIwindow\fR defaults to ``.''.
+\fIwindow\fR defaults to
+.QW . .
 .PP
 The second form of \fBselection own\fR causes \fIwindow\fR to become
 the new owner of \fIselection\fR on \fIwindow\fR's display, returning
@@ -160,9 +170,7 @@ proc lost {} {
    puts "Lost selection"
 }
 .CE
-
 .SH "SEE ALSO"
 clipboard(n)
-
 .SH KEYWORDS
 clear, format, handler, ICCCM, own, selection, target, type