Index: doc/StringObj.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/StringObj.3,v
retrieving revision 1.11
diff -u -r1.11 StringObj.3
--- doc/StringObj.3	24 Apr 2002 09:44:36 -0000	1.11
+++ doc/StringObj.3	26 Jun 2002 00:10:27 -0000
@@ -154,8 +154,19 @@
 representation is invalid (its byte pointer is NULL), the string
 representation is regenerated from the object's internal
 representation.  The storage referenced by the returned byte pointer
-is owned by the object manager and should not be modified by the
-caller.  The procedure \fBTcl_GetString\fR is used in the common case
+is owned by the object manager.  It is passed back as a writable
+pointer so that extension author creating their own \fBTcl_ObjType\fR
+will be able to modify the string representation within the
+\fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR.  Except for that
+limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR
+or \fBTcl_GetString\fR should be treated as read-only.  It is
+recommended that this pointer be assigned to a (CONST char *) variable.
+Even in the limited situations where writing to this pointer is
+acceptable, one should take care to respect the copy-on-write
+semantics required by \fBTcl_Obj\fR's, with appropriate calls
+to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any
+in-place modification of the string representation.
+The procedure \fBTcl_GetString\fR is used in the common case
 where the caller does not need the length of the string
 representation.
 .PP
