diff options
| -rw-r--r-- | ChangeLog | 6 | ||||
| -rw-r--r-- | doc/FileSystem.3 | 9 | ||||
| -rw-r--r-- | doc/Translate.3 | 17 |
3 files changed, 26 insertions, 6 deletions
@@ -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 |