More doc fix backporting

1 files changed, 43 insertions, 6 deletions

diff --git a/doc/file.n b/doc/file.n
index 7fc2b07..d97f2b0 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.23 2003/02/28 12:11:49 vincentdarley Exp $
+'\" RCS: @(#) $Id: file.n,v 1.23.2.1 2004/10/27 12:52:40 dkf Exp $
 '\" 
 .so man.macros
 .TH file n 8.3 Tcl "Tcl Built-In Commands"
@@ -101,7 +101,7 @@ overwritten unless the \fB\-force\fR option is specified.  When copying
 within a single filesystem, \fIfile copy\fR will copy soft links (i.e.
 the links themselves are copied, not the things they point to).  Trying
 to overwrite a non-empty directory, overwrite a directory with a file,
-or a file with a directory will all result in errors even if
+or overwrite a file with a directory will all result in errors even if
 \fI\-force\fR was specified.  Arguments are processed in the order
 specified, halting at the first error, if any.  A \fB\-\|\-\fR marks
 the end of switches; the argument following the \fB\-\|\-\fR will be
@@ -200,8 +200,8 @@ If only one argument is given, that argument is assumed to be
 seems to be the case with hard links, which look just like ordinary
 files), then an error is returned.
 .
-If 2 arguments are given, then these are assumed to be \fIlinkName\fR and
-\fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR
+If 2 arguments are given, then these are assumed to be \fIlinkName\fR
+and \fItarget\fR. If \fIlinkName\fR already exists, or if \fItarget\fR
 doesn't exist, an error will be returned.  Otherwise, Tcl creates a new
 link called \fIlinkName\fR which points to the existing filesystem object
 at \fItarget\fR, where the type of the link is platform-specific (on Unix
@@ -258,14 +258,14 @@ under Windows or AppleScript on the Macintosh.
 \fBfile normalize \fIname\fR
 .
 .RS
-Returns a unique normalised path representation for the file-system
+Returns a unique normalized path representation for the file-system
 object (file, directory, link, etc), whose string value can be used as a
 unique identifier for it.  A normalized path is an absolute path which has
 all '../', './' removed.  Also it is one which is in the ``standard''
 format for the native platform.  On MacOS, Unix, this means the segments
 leading up to the path must be free of symbolic links/aliases (but the
 very last path component may be a symbolic link), and on Windows it also
-means means we want the long form with that form's case-dependence (which
+means we want the long form with that form's case-dependence (which
 gives us a unique, case-dependent path).  The one exception concerning the
 last link in the path is necessary, because Tcl or the user may wish to
 operate on the actual symbolic link itself (for example 'file delete', 'file
@@ -418,6 +418,43 @@ Returns \fB1\fR if file \fIname\fR is writable by the current user,
 .
 These commands always operate using the real user and group identifiers,
 not the effective ones. 
+.SH EXAMPLES
+This procedure shows how to search for C files in a given directory
+that have a correspondingly-named object file in the current
+directory:
+.CS
+proc findMatchingCFiles {dir} {
+    set files {}
+    switch $::tcl_platform(platform) {
+        windows {
+            set ext .obj
+        }
+        unix {
+            set ext .o
+        }
+    }
+    foreach file [glob -nocomplain -directory $dir *.c] {
+        set objectFile [\fBfile\fR tail [\fBfile\fR rootname $file]]$ext
+        if {[\fBfile\fR exists $objectFile]} {
+            lappend files $file
+        }
+    }
+    return $files
+}
+.CE
+.PP
+Rename a file and leave a symbolic link pointing from the old location
+to the new place:
+.CS
+set oldName foobar.txt
+set newName foo/bar.txt
+# Make sure that where we're going to move to exists...
+if {![\fBfile\fR isdirectory [\fBfile\fR dirname $newName]]} {
+    \fBfile\fR mkdir [\fBfile\fR dirname $newName]
+}
+\fBfile\fR rename $oldName $newName
+\fBfile\fR link -symbolic $oldName $newName
+.CE
 
 .SH "SEE ALSO"
 filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),