summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorvincentdarley <vincentdarley>2003-07-28 12:16:01 (GMT)
committervincentdarley <vincentdarley>2003-07-28 12:16:01 (GMT)
commit73d0a6fc2d48ac4bea1e1ed96781bdd37c33647f (patch)
tree13eb1a809bb0252d4c7210e93b1fd8a49019cf53
parent36f1698a072c40091f4452ae29366b10cc4be03c (diff)
downloadtcl-73d0a6fc2d48ac4bea1e1ed96781bdd37c33647f.zip
tcl-73d0a6fc2d48ac4bea1e1ed96781bdd37c33647f.tar.gz
tcl-73d0a6fc2d48ac4bea1e1ed96781bdd37c33647f.tar.bz2
documentation fix, bug 775220
-rw-r--r--ChangeLog6
-rw-r--r--doc/FileSystem.39
-rw-r--r--doc/Translate.317
3 files changed, 26 insertions, 6 deletions
diff --git a/ChangeLog b/ChangeLog
index b4497cf..1b02c6c 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2003-07-28 Vince Darley <vincentdarley@users.sourceforge.net>
+
+ * doc/FileSystem.3:
+ * doc/Translate.3: better documentation of Tcl_TranslateFileName
+ and related functions [Bug 775220]
+
2003-07-24 Mo DeJong <mdejong@users.sourceforge.net>
* generic/tcl.h: Revert change made on 2003-07-21
diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index 0853ccc..c7113b9 100644
--- a/doc/FileSystem.3
+++ b/doc/FileSystem.3
@@ -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: FileSystem.3,v 1.33 2003/06/23 10:45:54 vincentdarley Exp $
+'\" RCS: @(#) $Id: FileSystem.3,v 1.34 2003/07/28 12:16:02 vincentdarley Exp $
'\"
.so man.macros
.TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
@@ -550,10 +550,15 @@ If the translation succeeds (i.e. the object is a valid path), then it
is returned. Otherwise NULL will be returned, and an error message may
be left in the interpreter. A "translated" path is one which
contains no "~" or "~user" sequences (these have been expanded to
-their current representation in the filesystem).
+their current representation in the filesystem). This function is of
+little practical use, and \fBTcl_FSGetNormalizedPath\fR or
+\fBTcl_GetNativePath\fR are usually better functions to use for most
+purposes.
.PP
\fBTcl_FSGetTranslatedStringPath\fR does the same as
\fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
+Again, \fBTcl_FSGetNormalizedPath\fR or \fBTcl_GetNativePath\fR are
+usually better functions to use for most purposes.
.PP
\fBTcl_FSNewNativePath\fR performs something like that reverse of the
usual obj->path->nativerep conversions. If some code retrieves a path
diff --git a/doc/Translate.3 b/doc/Translate.3
index 1e26d4d..5602424 100644
--- a/doc/Translate.3
+++ b/doc/Translate.3
@@ -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: Translate.3,v 1.6 2002/02/08 02:52:54 dgp Exp $
+'\" RCS: @(#) $Id: Translate.3,v 1.7 2003/07/28 12:16:02 vincentdarley Exp $
'\"
.so man.macros
.TH Tcl_TranslateFileName 3 8.1 Tcl "Tcl Library Procedures"
@@ -33,9 +33,18 @@ anything stored here.
.SH DESCRIPTION
.PP
-This utility procedure translates a file name to a form suitable for
-passing to the local operating system. It converts network names into
-native form and does tilde substitution.
+This utility procedure translates a file name to a platform-specific form
+which, after being converted to the appropriate encoding, is suitable for
+passing to the local operating system. In particular, it converts
+network names into native form and does tilde substitution.
+.PP
+However, with the advent of the newer \fBTcl_FSGetNormalizedPath\fR and
+\fBTcl_GetNativePath\fR, there is no longer any need to use this
+procedure. In particular, \fBTcl_GetNativePath\fR performs all the
+necessary translation and encoding conversion, is virtual-filesystem
+aware, and caches the native result for faster repeated calls.
+Finally \fBTcl_GetNativePath\fR does not require you to free anything
+afterwards.
.PP
If
\fBTcl_TranslateFileName\fR has to do tilde substitution or translate