Update documentation, matching current implementation

Author: jan.nijtmans

doc/encoding.n

@@ -28,7 +28,7 @@ formats.
 Performs one of several encoding related operations, depending on
 \fIoption\fR.  The legal \fIoption\fRs are:
 .TP
-\fBencoding convertfrom\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR? ?\fB-strict\fR? ?\fIencoding\fR? \fIdata\fR
+\fBencoding convertfrom\fR ?\fB-nocomplain\fR|\fB-strict\fR|\fB-failindex var\fR? ?\fIencoding\fR? \fIdata\fR
 .
 Convert \fIdata\fR to a Unicode string from the specified \fIencoding\fR.  The
 characters in \fIdata\fR are 8 bit binary data.  The resulting
@@ -48,19 +48,19 @@ in case of a conversion error, the position of the input byte causing the error
 is returned in the given variable.  The return value of the command are the
 converted characters until the first error position.
 In case of no error, the value \fI-1\fR is written to the variable.  This option
-may not be used together with \fB-nocomplain\fR.
+may not be used together with \fB-nocomplain\fR or \fB-strict\fR.
 .PP
 The option \fB-nocomplain\fR has no effect and is available for compatibility with
 TCL 9. In TCL 9, the encoding command fails with an error on any encoding issue.
 This switch restores the TCL8.7 behaviour.
 .PP
 The \fB-strict\fR option follows more strict rules in conversion.  For the \fButf-8\fR
-encoder, it disallows the the sequence \fB\\xC0\\x80\fR and noncharacters (which -
+encoder, it disallows invalid byte sequences and surrogates (which -
 otherwise - are just passed through).
 .VE "TCL8.7 TIP346, TIP607, TIP601"
 .RE
 .TP
-\fBencoding convertto\fR ?\fB-nocomplain\fR? ?\fB-failindex var\fR? ?\fB-strict\fR? ?\fIencoding\fR? \fIstring\fR
+\fBencoding convertto\fR ?\fB-nocomplain\fR|\fB-strict\fR|\fB-failindex var\fR? ?\fIencoding\fR? \fIstring\fR
 .
 Convert \fIstring\fR from Unicode to the specified \fIencoding\fR.
 The result is a sequence of bytes that represents the converted
@@ -81,15 +81,14 @@ in case of a conversion error, the position of the input character causing the e
 is returned in the given variable.  The return value of the command are the
 converted bytes until the first error position. No error condition is raised.
 In case of no error, the value \fI-1\fR is written to the variable.  This option
-may not be used together with \fB-nocomplain\fR.
+may not be used together with \fB-nocomplain\fR or \fB-strict\fR.
 .PP
 The option \fB-nocomplain\fR has no effect and is available for compatibility with
 TCL 9. In TCL 9, the encoding command fails with an error on any encoding issue.
 This switch restores the TCL8.7 behaviour.
 .PP
 The \fB-strict\fR option follows more strict rules in conversion.  For the \fButf-8\fR
-encoder, it disallows the the sequence \fB\\xC0\\x80\fR and noncharacters (which -
-otherwise - are just passed through).
+encoder, it disallows surrogates (which - otherwise - are just passed through).
 .VE "TCL8.7 TIP346, TIP607, TIP601"
 .RE
 .TP

generic/tclCmdAH.c

@@ -610,7 +610,7 @@ EncodingConvertfromObjCmd(
 	}
     } else {
     encConvFromError:
-	Tcl_WrongNumArgs(interp, 1, objv, "?-nocomplain? ?-strict? ?-failindex var? ?encoding? data");
+	Tcl_WrongNumArgs(interp, 1, objv, "?-nocomplain|-strict|-failindex var? ?encoding? data");
 	return TCL_ERROR;
     }
 
@@ -749,7 +749,7 @@ EncodingConverttoObjCmd(
 	}
     } else {
     encConvToError:
-	Tcl_WrongNumArgs(interp, 1, objv, "?-nocomplain? ?-strict? ?-failindex var? ?encoding? data");
+	Tcl_WrongNumArgs(interp, 1, objv, "?-nocomplain|-strict|-failindex var? ?encoding? data");
 	return TCL_ERROR;
     }
 

tests/cmdAH.test

@@ -179,7 +179,7 @@ test cmdAH-4.2 {Tcl_EncodingObjCmd} -returnCodes error -body {
 } -result {unknown or ambiguous subcommand "foo": must be convertfrom, convertto, dirs, names, or system}
 test cmdAH-4.3 {Tcl_EncodingObjCmd} -returnCodes error -body {
     encoding convertto
-} -result {wrong # args: should be "encoding convertto ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -result {wrong # args: should be "encoding convertto ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test cmdAH-4.4 {Tcl_EncodingObjCmd} -returnCodes error -body {
     encoding convertto foo bar
 } -result {unknown encoding "foo"}
@@ -201,7 +201,7 @@ test cmdAH-4.6 {Tcl_EncodingObjCmd} -setup {
 } -result 8C
 test cmdAH-4.7 {Tcl_EncodingObjCmd} -returnCodes error -body {
     encoding convertfrom
-} -result {wrong # args: should be "encoding convertfrom ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -result {wrong # args: should be "encoding convertfrom ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test cmdAH-4.8 {Tcl_EncodingObjCmd} -returnCodes error -body {
     encoding convertfrom foo bar
 } -result {unknown encoding "foo"}
@@ -238,10 +238,10 @@ test cmdAH-4.13 {Tcl_EncodingObjCmd} -setup {
 
 test cmdAH-4.14.1 {Syntax error, -nocomplain and -failindex, no encoding} -body {
     encoding convertfrom -nocomplain -failindex 2 ABC
-} -returnCodes 1 -result {wrong # args: should be "encoding convertfrom ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -returnCodes 1 -result {wrong # args: should be "encoding convertfrom ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test cmdAH-4.14.2 {Syntax error, -nocomplain and -failindex, no encoding} -body {
     encoding convertto -nocomplain -failindex 2 ABC
-} -returnCodes 1 -result {wrong # args: should be "encoding convertto ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -returnCodes 1 -result {wrong # args: should be "encoding convertto ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test cmdAH-4.15.1 {Syntax error, -failindex and -nocomplain, no encoding} -body {
     encoding convertfrom -failindex 2 -nocomplain ABC
 } -returnCodes 1 -result {unknown encoding "-nocomplain"}
@@ -250,40 +250,40 @@ test cmdAH-4.15.2 {Syntax error, -failindex and -nocomplain, no encoding} -body
 } -returnCodes 1 -result {unknown encoding "-nocomplain"}
 test cmdAH-4.16.1 {Syntax error, -nocomplain and -failindex, encoding} -body {
     encoding convertfrom -nocomplain -failindex 2 utf-8 ABC
-} -returnCodes 1 -result {wrong # args: should be "encoding convertfrom ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -returnCodes 1 -result {wrong # args: should be "encoding convertfrom ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test cmdAH-4.16.2 {Syntax error, -nocomplain and -failindex, encoding} -body {
     encoding convertto -nocomplain -failindex 2 utf-8 ABC
-} -returnCodes 1 -result {wrong # args: should be "encoding convertto ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -returnCodes 1 -result {wrong # args: should be "encoding convertto ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test cmdAH-4.17.1 {Syntax error, -failindex and -nocomplain, encoding} -body {
     encoding convertfrom -failindex 2 -nocomplain utf-8 ABC
-} -returnCodes 1 -result {wrong # args: should be "encoding convertfrom ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -returnCodes 1 -result {wrong # args: should be "encoding convertfrom ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test cmdAH-4.17.2 {Syntax error, -failindex and -nocomplain, encoding} -body {
     encoding convertto -failindex 2 -nocomplain utf-8 ABC
-} -returnCodes 1 -result {wrong # args: should be "encoding convertto ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -returnCodes 1 -result {wrong # args: should be "encoding convertto ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test cmdAH-4.18.1 {Syntax error, -failindex with no var, no encoding} -body {
     encoding convertfrom -failindex ABC
-} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertfrom ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertfrom ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test cmdAH-4.18.2 {Syntax error, -failindex with no var, no encoding (byte compiled)} -setup {
     proc encoding_test {} {
         encoding convertfrom -failindex ABC
     }
 } -body {
     # Compile and execute
     encoding_test
-} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertfrom ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"} -cleanup {
+} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertfrom ?-nocomplain|-strict|-failindex var? ?encoding? data"} -cleanup {
     rename encoding_test ""
 }
 test cmdAH-4.18.3 {Syntax error, -failindex with no var, no encoding} -body {
     encoding convertto -failindex ABC
-} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertto ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertto ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test cmdAH-4.18.4 {Syntax error, -failindex with no var, no encoding (byte compiled)} -setup {
     proc encoding_test {} {
         encoding convertto -failindex ABC
     }
 } -body {
     # Compile and execute
     encoding_test
-} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertto ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"} -cleanup {
+} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertto ?-nocomplain|-strict|-failindex var? ?encoding? data"} -cleanup {
     rename encoding_test ""
 }
 test cmdAH-4.19.1 {convertrom -failindex with correct data} -body {

tests/encoding.test

@@ -681,10 +681,10 @@ test encoding-24.21 {Parse with -nocomplain but without providing encoding} {
 } 1
 test encoding-24.22 {Syntax error, two encodings} -body {
     encoding convertfrom iso8859-1 utf-8 "ZX\uD800"
-} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertfrom ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertfrom ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test encoding-24.23 {Syntax error, two encodings} -body {
     encoding convertto iso8859-1 utf-8 "ZX\uD800"
-} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertto ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -returnCodes 1 -result {wrong # args: should be "::tcl::encoding::convertto ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test encoding-24.24 {Parse invalid utf-8 with -strict} -body {
     encoding convertfrom -strict utf-8 "\xC0\x80\x00\x00"
 } -returnCodes 1 -result {unexpected byte sequence starting at index 0: '\xC0'}

tests/safe.test

@@ -1473,7 +1473,7 @@ test safe-11.7 {testing safe encoding} -setup {
     interp eval $i encoding convertfrom
 } -returnCodes error -cleanup {
     safe::interpDelete $i
-} -result {wrong # args: should be "encoding convertfrom ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -result {wrong # args: should be "encoding convertfrom ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test safe-11.7.1 {testing safe encoding} -setup {
     set i [safe::interpCreate]
 } -body {
@@ -1482,7 +1482,7 @@ test safe-11.7.1 {testing safe encoding} -setup {
 } -match glob -cleanup {
     unset -nocomplain m o
     safe::interpDelete $i
-} -result {wrong # args: should be "encoding convertfrom ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"
+} -result {wrong # args: should be "encoding convertfrom ?-nocomplain|-strict|-failindex var? ?encoding? data"
     while executing
 "encoding convertfrom"
     invoked from within
@@ -1495,7 +1495,7 @@ test safe-11.8 {testing safe encoding} -setup {
     interp eval $i encoding convertto
 } -returnCodes error -cleanup {
     safe::interpDelete $i
-} -result {wrong # args: should be "encoding convertto ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"}
+} -result {wrong # args: should be "encoding convertto ?-nocomplain|-strict|-failindex var? ?encoding? data"}
 test safe-11.8.1 {testing safe encoding} -setup {
     set i [safe::interpCreate]
 } -body {
@@ -1504,7 +1504,7 @@ test safe-11.8.1 {testing safe encoding} -setup {
 } -match glob -cleanup {
     unset -nocomplain m o
     safe::interpDelete $i
-} -result {wrong # args: should be "encoding convertto ?-nocomplain? ?-strict? ?-failindex var? ?encoding? data"
+} -result {wrong # args: should be "encoding convertto ?-nocomplain|-strict|-failindex var? ?encoding? data"
     while executing
 "encoding convertto"
     invoked from within