From a3581baf860f2a375a2e47178c6c15eac3f919aa Mon Sep 17 00:00:00 2001
From: apnadkarni <apnmbx-wits@yahoo.com>
Date: Mon, 24 Jul 2023 05:40:38 +0000
Subject: Docs - tilde substitution and unsigned int->size_t in Tcl_Alloc

---
 doc/Alloc.3    |  2 +-
 doc/filename.n | 16 ++++++++++++++++
 doc/tclvars.n  |  4 ++++
 doc/tm.n       |  4 ++++
 4 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/doc/Alloc.3 b/doc/Alloc.3
index c0fd0cd..d1db8d4 100644
--- a/doc/Alloc.3
+++ b/doc/Alloc.3
@@ -32,7 +32,7 @@ void
 \fBTcl_GetMemoryInfo\fR(\fIdsPtr\fR)
 .SH ARGUMENTS
 .AS char *size
-.AP "unsigned int" size in
+.AP "size_t" size in
 Size in bytes of the memory block to allocate.
 .AP char *ptr in
 Pointer to memory block to free or realloc.
diff --git a/doc/filename.n b/doc/filename.n
index 628b2bb..b44b17b 100644
--- a/doc/filename.n
+++ b/doc/filename.n
@@ -119,6 +119,22 @@ Volume-relative path to a file \fBfoo\fR in the root directory of the current
 volume.  This is not a valid UNC path, so the assumption is that the
 extra backslashes are superfluous.
 .RE
+.SH "TILDE SUBSTITUTION"
+.PP
+Unlike earlier versions of Tcl, Tcl 9 does not do implicit tilde substitution
+on file paths with the exception noted below. The commands \fBfile home\fR and
+\fBfile tildeexpand\fR may be used to explicitly accomplish the same.
+.PP
+The exception to the above is initialization of the \fBauto_path\fR variable
+and the Tcl module search paths as documented in the manpages for
+\fBtclvars\fR and \fBtm\fR. When any path in an environment variable used to
+initialize these starts with a tilde, it will be interpreted as if the first
+element is replaced with the location of the home directory for the given
+user. If the tilde is followed immediately by a separator, the
+\fB$HOME\fR environment variable is substituted. Otherwise the characters
+between the tilde and the next separator are taken as a user name, which is
+used to retrieve the user's home directory for substitution. This works on
+POSIX, MacOS X and Windows platforms.
 .SH "PORTABILITY ISSUES"
 .PP
 Not all file systems are case sensitive, so scripts should avoid code
diff --git a/doc/tclvars.n b/doc/tclvars.n
index d244953..49e86a5 100644
--- a/doc/tclvars.n
+++ b/doc/tclvars.n
@@ -30,6 +30,10 @@ the parent directory of \fBtcl_library\fR,
 the directories listed in the \fBtcl_pkgPath\fR variable.
 Additional locations to look for files and package indices should
 normally be added to this variable using \fBlappend\fR.
+Initialization of auto_path from the TCLLIBPATH environment
+variable undergoes tilde substitution (see \fBfilename\fR) on each
+path. Any tilde substitution that fails because the user is unknown
+will be omitted from auto_path.
 .RS
 .PP
 Additional variables relating to package management exist. More
diff --git a/doc/tm.n b/doc/tm.n
index bdc167a..27ce673 100644
--- a/doc/tm.n
+++ b/doc/tm.n
@@ -295,6 +295,10 @@ environment variables:
 \fB$::env(TCL8.1_TM_PATH)\fR  \fB$::env(TCL8_1_TM_PATH)\fR
 \fB$::env(TCL8.0_TM_PATH)\fR  \fB$::env(TCL8_0_TM_PATH)\fR
 .CE
+.PP
+Paths initialized from the environment variables undergo tilde
+substitution (see \fBfilename\fR). Any path whose tilde substitution
+fails because the user is unknown will be omitted from search paths.
 .SH "SEE ALSO"
 package(n), Tcl Improvement Proposal #189
 .QW "\fITcl Modules\fR"
-- 
cgit v0.12