improved filesystem documentation

3 files changed, 55 insertions, 44 deletions

diff --git a/doc/file.n b/doc/file.n
index ce699aa..0658009 100644
--- a/doc/file.n
+++ b/doc/file.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: file.n,v 1.25 2003/07/07 08:57:58 vincentdarley Exp $
+'\" RCS: @(#) $Id: file.n,v 1.26 2003/12/12 17:02:13 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH file n 8.3 Tcl "Tcl Built-In Commands"
@@ -220,13 +220,16 @@ error if for some reason that is not possible), then the optional
 \fI-linktype\fR argument should be given.  Accepted values for
 \fI-linktype\fR are "-symbolic" and "-hard".
 .
-When creating links on filesystems that either do not support any links,
-or do not support the specific type requested, an error message will be
-returned.  In particular Windows 95, 98 and ME do not support any links
-at present, but most Unix platforms support both symbolic and hard links
-(the latter for files only), MacOS supports symbolic links and Windows
-NT/2000/XP (on NTFS drives) support symbolic directory links and hard
-file links.
+On Unix, symbolic links can be made to relative paths, but on all other
+platforms target paths will be converted to absolute, normalized form
+before the link is created (and "~user" paths are always expanded to
+absolute form).  When creating links on filesystems that
+either do not support any links, or do not support the specific type
+requested, an error message will be returned.  In particular Windows 95,
+98 and ME do not support any links at present, but most Unix platforms
+support both symbolic and hard links (the latter for files only), MacOS
+supports symbolic links and Windows NT/2000/XP (on NTFS drives) support
+symbolic directory links and hard file links.
 .TP
 \fBfile lstat \fIname varName\fR
 .
diff --git a/doc/filename.n b/doc/filename.n
index de77d8c..5427c1d 100644
--- a/doc/filename.n
+++ b/doc/filename.n
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: filename.n,v 1.8 2003/09/16 14:56:08 vincentdarley Exp $
+'\" RCS: @(#) $Id: filename.n,v 1.9 2003/12/12 17:02:13 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH filename n 7.5 Tcl "Tcl Built-In Commands"
@@ -45,16 +45,16 @@ The rules for native names depend on the value reported in the Tcl
 array element \fBtcl_platform(platform)\fR:
 .TP 10
 \fBmac\fR
-On Apple Macintosh systems, Tcl supports two forms of path names.  The
-normal Mac style names use colons as path separators.  Paths may be
-relative or absolute, and file names may contain any character other
-than colon.  A leading colon causes the rest of the path to be
-interpreted relative to the current directory.  If a path contains a
-colon that is not at the beginning, then the path is interpreted as an
-absolute path.  Sequences of two or more colons anywhere in the path
-are used to construct relative paths where \fB::\fR refers to the
-parent of the current directory, \fB:::\fR refers to the parent of the
-parent, and so forth.
+On Apple Macintosh Classic systems (i.e. with MacOS 9.x or older), Tcl
+supports two forms of path names.  The normal Mac style names use colons
+as path separators.  Paths may be relative or absolute, and file names
+may contain any character other than colon.  A leading colon causes the
+rest of the path to be interpreted relative to the current directory.
+If a path contains a colon that is not at the beginning, then the path
+is interpreted as an absolute path.  Sequences of two or more colons
+anywhere in the path are used to construct relative paths where \fB::\fR
+refers to the parent of the current directory, \fB:::\fR refers to the
+parent of the parent, and so forth.
 .RS
 .PP
 In addition to Macintosh style names, Tcl also supports a subset of
@@ -100,13 +100,14 @@ current folder.
 .RE
 .TP
 \fBunix\fR
-On Unix platforms, Tcl uses path names where the components are
-separated by slashes.  Path names may be relative or absolute, and
-file names may contain any character other than slash.  The file names
-\fB\&.\fR and \fB\&..\fR are special and refer to the current directory
-and the parent of the current directory respectively.  Multiple
-adjacent slash characters are interpreted as a single separator.
-The following examples illustrate various forms of path names:
+On Unix and Apple MacOS X platforms, Tcl uses path names where the
+components are separated by slashes.  Path names may be relative or
+absolute, and file names may contain any character other than slash.
+The file names \fB\&.\fR and \fB\&..\fR are special and refer to the
+current directory and the parent of the current directory respectively.
+Multiple adjacent slash characters are interpreted as a single
+separator.  The following examples illustrate various forms of path
+names:
 .RS
 .TP 15
 \fB/\fR
@@ -175,24 +176,24 @@ extra backslashes are superfluous.
 .SH "TILDE SUBSTITUTION"
 .PP
 In addition to the file name rules described above, Tcl also supports
-\fIcsh\fR-style tilde substitution.  If a file name starts with a
-tilde, then the file name 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, then 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.
+\fIcsh\fR-style tilde substitution.  If a file name starts with a tilde,
+then the file name 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, then 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
+Unix, MacOS X and Windows (except very old releases).
 .PP
-The Macintosh and Windows platforms do not support tilde substitution
-when a user name follows the tilde.  On these platforms, attempts to
-use a tilde followed by a user name will generate an error that the
-user does not exist when Tcl attempts to interpret that part of the
-path or otherwise access the file.  The behaviour of these paths
-when not trying to interpret them is the same as on Unix.  File
-names that have a tilde without a user name will be correctly
-substituted using the \fB$HOME\fR environment variable, just like 
-for Unix.
+The Classic Macintosh (OS 9 and older) platform and old Windows
+platforms do not support tilde substitution when a user name follows the
+tilde.  On these platforms, attempts to use a tilde followed by a user
+name will generate an error that the user does not exist when Tcl
+attempts to interpret that part of the path or otherwise access the
+file.  The behaviour of these paths when not trying to interpret them is
+the same as on Unix.  File names that have a tilde without a user name
+will be correctly substituted using the \fB$HOME\fR environment
+variable, just like for Unix.
 
 .SH "PORTABILITY ISSUES"
 .PP
diff --git a/doc/glob.n b/doc/glob.n
index 15ae60c..e4df23d 100644
--- a/doc/glob.n
+++ b/doc/glob.n
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: glob.n,v 1.12 2002/07/01 18:24:39 jenglish Exp $
+'\" RCS: @(#) $Id: glob.n,v 1.13 2003/12/12 17:02:13 vincentdarley Exp $
 '\" 
 .so man.macros
 .TH glob n 8.3 Tcl "Tcl Built-In Commands"
@@ -149,6 +149,13 @@ command if you want the list sorted).
 Second, \fBglob\fR only returns the names of files that actually
 exist;  in csh no check for existence is made unless a pattern
 contains a ?, *, or [] construct.
+.LP
+When the \fBglob\fR command returns relative paths whose filenames
+start with a tilde ``~'' (for example through \fBglob *\fR or 
+\fBglob -tails\fR, the returned list will not quote the tilde with
+``./''.  This means care must be taken if those names are later to
+be used with \fBfile join\fR, to avoid them being interpreted as
+absolute paths pointing to a given user's home directory.
 
 .SH "PORTABILITY ISSUES"
 .PP