From b0bcd99f0853484343dec35867a3db0aeafd1bba Mon Sep 17 00:00:00 2001
From: oehhar <harald.oehlmann@elmicron.de>
Date: Mon, 6 Nov 2023 15:10:18 +0000
Subject: Refine read and gets documentation for encoding error case

---
 doc/gets.n |  8 +++++---
 doc/read.n | 10 +++++-----
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/doc/gets.n b/doc/gets.n
index 59e00c7..29355a4 100644
--- a/doc/gets.n
+++ b/doc/gets.n
@@ -61,7 +61,7 @@ continued multi-byte sequence at position 1 (\fBA \\xC3 B\fR):
 .PP
 File creation for example
 .CS
-% set f [open test_A_195_B.txt wb]; puts -nonewline $f A\xC3B; close $f
+% set f [open test_A_195_B.txt wb]; puts -nonewline $f A\\xC3B; close $f
 .CE
 Encoding error example
 .CS
@@ -71,7 +71,7 @@ file384b6a8
 % catch {gets $f} e d
 1
 % set d
--data A -code 1 -level 0
+-code 1 -level 0
 -errorstack {INNER {invokeStk1 gets file384b6a8}}
 -errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}}
 -errorinfo {...} -errorline 1
@@ -81,7 +81,9 @@ file384b6a8
 % gets $f
 AÃB
 .CE
-ToDo: -data is TIP 653 and may be removed here or explained.
+Compared to \fBread\fR, any already decoded data is not consumed.
+The file position is still at 0 and the recovery \fBgets\fR returns also the
+already well decoded leading data.
 .SH "EXAMPLE"
 This example reads a file one line at a time and prints it out with
 the current line number attached to the start of each line.
diff --git a/doc/read.n b/doc/read.n
index c1291bf..2add683 100644
--- a/doc/read.n
+++ b/doc/read.n
@@ -54,7 +54,8 @@ which \fBfconfigure\fR will alter input.
 .PP
 Encoding errors may exist, if the encoding profile \fBstrict\fR is used.
 Encoding errors are special, as an eventual introspection or  recovery is
-possible by changing to an encoding which accepts the data.
+possible by changing to an encoding (or encoding profile), which accepts
+the data.
 An encoding error is reported by the POSIX error code \fBEILSEQ\fR.
 .PP
 In blocking mode, the error is directly thrown, even, if there is a
@@ -75,7 +76,7 @@ continued multi-byte sequence at position 1 (\fBA \\xC3 B\fR):
 File creation for examples
 .
 .CS
-% set f [open test_A_195_B.txt wb]; puts -nonewline $f A\xC3B; close $f
+% set f [open test_A_195_B.txt wb]; puts -nonewline $f A\\xC3B; close $f
 .CE
 Blocking example
 .
@@ -86,7 +87,7 @@ file35a65a0
 % catch {read $f} e d
 1
 % set d
--data A -code 1 -level 0
+-code 1 -level 0
 -errorstack {INNER {invokeStk1 read file35a65a0}}
 -errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}}
 -errorinfo {...} -errorline 1
@@ -110,12 +111,11 @@ A
 % catch {read $f} e d
 1
 % set d
--data {} -code 1 -level 0
+-code 1 -level 0
 -errorstack {INNER {invokeStk1 read file384b228}}
 -errorcode {POSIX EILSEQ {invalid or incomplete multibyte or wide character}}
 -errorinfo {...} -errorline 1
 .CE
-ToDo: -data is TIP 653 and may be removed here or explained.
 .SH "USE WITH SERIAL PORTS"
 '\" Note:  this advice actually applies to many versions of Tcl
 .PP
-- 
cgit v0.12