summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorvincentdarley <vincentdarley>2003-12-12 17:02:13 (GMT)
committervincentdarley <vincentdarley>2003-12-12 17:02:13 (GMT)
commit40b6f0c8bf1edab6618ea5c61cea14cf3a5c5443 (patch)
tree8d8e536a5def41a544a5006aac189da2a81c2dcb
parentbcae87dcfb91b941c363621ebfe6e5bd33a33fee (diff)
downloadtcl-40b6f0c8bf1edab6618ea5c61cea14cf3a5c5443.zip
tcl-40b6f0c8bf1edab6618ea5c61cea14cf3a5c5443.tar.gz
tcl-40b6f0c8bf1edab6618ea5c61cea14cf3a5c5443.tar.bz2
improved filesystem documentation
-rw-r--r--doc/file.n19
-rw-r--r--doc/filename.n71
-rw-r--r--doc/glob.n9
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