Merge 9.0. Update documentation

1 files changed, 6 insertions, 5 deletions

diff --git a/doc/Utf.3 b/doc/Utf.3
index 2c24c85..2a1294f 100644
--- a/doc/Utf.3
+++ b/doc/Utf.3
@@ -166,11 +166,12 @@ can consume in a single call.
 .PP
 \fBTcl_UniCharToUtf\fR stores the character \fIch\fR as a UTF-8 string
 in starting at \fIbuf\fR.  The return value is the number of bytes stored
-in \fIbuf\fR. If ch is a high surrogate (range U+D800 - U+DBFF), then
-the return value will be 1 and a single byte in the range 0xF0 - 0xF4
-will be stored. If you still want to produce UTF-8 output for it (even
-though knowing it's an illegal code-point on its own), just call
-\fBTcl_UniCharToUtf\fR again specifying ch = -1.
+in \fIbuf\fR. The character \fIch\fR can be or'ed with the value TCL_COMBINE
+to enable special behavior, compatible with Tcl 8.x. Then, if ch is a high
+surrogate (range U+D800 - U+DBFF), the return value will be 1 and a single
+byte in the range 0xF0 - 0xF4 will be stored. If \fIch\fR is a low surrogate
+(range U+DC00 - U+DFFF), an attempt is made to combine the result with
+the earlier produced bytes, resulting in a 4-byte UTF-8 byte sequence.
 .PP
 \fBTcl_UtfToUniChar\fR reads one UTF-8 character starting at \fIsrc\fR
 and stores it as a Tcl_UniChar in \fI*chPtr\fR.  The return value is the