Clarify filesystem docs

1 files changed, 152 insertions, 153 deletions

diff --git a/doc/FileSystem.3 b/doc/FileSystem.3
index b7f1602..e874e8c 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.48 2004/09/27 15:07:56 vincentdarley Exp $
+'\" RCS: @(#) $Id: FileSystem.3,v 1.49 2004/10/07 08:49:37 dkf Exp $
 '\" 
 .so man.macros
 .TH Filesystem 3 8.4 Tcl "Tcl Library Procedures"
@@ -63,10 +63,11 @@ int
 \fBTcl_FSEvalFile\fR(\fIinterp, pathPtr\fR)
 .sp
 int
-\fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr, handlePtr, unloadProcPtr\fR)
+\fBTcl_FSLoadFile\fR(\fIinterp, pathPtr, sym1, sym2, proc1Ptr, proc2Ptr,
+               handlePtr, unloadProcPtr\fR)
 .sp
 int
-\fBTcl_FSMatchInDirectory\fR(\fIinterp, result, pathPtr, pattern, types\fR)
+\fBTcl_FSMatchInDirectory\fR(\fIinterp, resultPtr, pathPtr, pattern, types\fR)
 .sp
 Tcl_Obj*
 \fBTcl_FSLink\fR(\fIlinkNamePtr, toPtr, linkAction\fR)
@@ -143,7 +144,7 @@ Tcl_Obj*
 Tcl_StatBuf*
 \fBTcl_AllocStatBuf\fR()
 .SH ARGUMENTS
-.AS "CONST char" *encodingName in
+.AS Tcl_FSUnloadFileProc **unloadProcPtr out
 .AP Tcl_Filesystem *fsPtr in
 Points to a structure containing the addresses of procedures that
 can be called to perform the various filesystem operations.
@@ -161,13 +162,10 @@ rename operation.
 The encoding of the data stored in the
 file identified by \fIpathPtr\fR and to be evaluted.
 .AP "CONST char" *pattern in
-Only files or directories matching this pattern will be returned by
-\fBTcl_FSMatchInDirectory\fR.
+Only files or directories matching this pattern will be returned.
 .AP Tcl_GlobTypeData *types in
 Only files or directories matching the type descriptions contained in
-this structure will be returned by \fBTcl_FSMatchInDirectory\fR.  It
-is very important that the 'directory' and 'mount' flags are properly handled.
-This parameter may be NULL.
+this structure will be returned.  This parameter may be NULL.
 .AP Tcl_Interp *interp in
 Interpreter to use either for results, evaluation, or reporting error
 messages.
@@ -189,11 +187,10 @@ In the case of an error, filled with an object containing the name of
 the file which caused an error in the various copy/rename operations.
 .AP Tcl_Obj **objPtrRef out
 Filled with an object containing the result of the operation.
-.AP Tcl_Obj *result out
+.AP Tcl_Obj *resultPtr out
 Pre-allocated object in which to store (using
 \fBTcl_ListObjAppendElement\fR) the list of
-files or directories which are successfully matched in
-\fBTcl_FSMatchInDirectory\fR.
+files or directories which are successfully matched.
 .AP int mode in
 Mask consisting of one or more of R_OK, W_OK, X_OK and F_OK.  R_OK,
 W_OK and X_OK request checking whether the file exists and  has  read,
@@ -212,7 +209,7 @@ Filled with the safe-init function for this code.
 .AP ClientData *clientDataPtr out
 Filled with the clientData value to pass to this code's unload
 function when it is called.
-.AP TclfsUnloadFileProc_ **unloadProcPtr out
+.AP Tcl_FSUnloadFileProc **unloadProcPtr out
 Filled with the function to use to unload this piece of code.
 .AP utimbuf *tval in
 The access and modification times in this structure are read and
@@ -285,8 +282,8 @@ Tcl_Obj *path = Tcl_NewStringObj(...);
 Tcl_FS\fIWhatever\fR(path);
 Tcl_DecrRefCount(path);
 .CE
-is wrong, and may cause memory errors.
-The \fIpath\fR must have its reference count incremented before passing it in, or
+is wrong, and may cause memory errors. The \fIpath\fR must have its
+reference count incremented before passing it in, or
 decrementing it.  For this reason, objects with a reference count of zero are
 considered not to be valid filesystem paths and calling any Tcl_FS API
 function with such an object will result in no action being taken.
@@ -670,8 +667,7 @@ heap (which may be deallocated by being passed to \fBckfree\fR.)  This
 allows extensions to invoke \fBTcl_FSStat\fR and \fBTcl_FSLStat\fR
 without being dependent on the size of the buffer.  That in turn
 depends on the flags used to build Tcl.
-.PP
-.SH TCL_FILESYSTEM
+.SH "THE VIRTUAL FILESYSTEM API"
 .PP
 A filesystem provides a \fBTcl_Filesystem\fR structure that contains
 pointers to functions that implement the various operations on a
@@ -700,6 +696,7 @@ return NULL.
 the set of mount points for the given (already registered) filesystem
 have changed, and that cached file representations may therefore no
 longer be correct.
+.SS "THE TCL_FILESYSTEM STRUCTURE"
 .PP
 The \fBTcl_Filesystem\fR structure contains the following fields:
 .CS
@@ -763,9 +760,14 @@ fallbacks occur.  This is true except for the last four entries in the
 filesystem table (\fBlstat\fR, \fBload\fR, \fBgetcwd\fR and \fBchdir\fR)
 for which fallbacks do in fact occur at the C level.
 .PP
-As an example, here is the filesystem lookup table used by the
-"vfs" extension which allows filesystem actions to be implemented
-in Tcl.
+Any functions which take path names in Tcl_Obj form take
+those names in UTF\-8 form.  The filesystem infrastructure API is
+designed to support efficient, cached conversion of these UTF\-8 paths
+to other native representations.
+.SS "EXAMPLE FILESYSTEM DEFINITION"
+.PP
+Here is the filesystem lookup table used by the "vfs" extension which
+allows filesystem actions to be implemented in Tcl.
 .CS
 static Tcl_Filesystem vfsFilesystem = {
     "tclvfs",
@@ -774,14 +776,15 @@ static Tcl_Filesystem vfsFilesystem = {
     &VfsPathInFilesystem,
     &VfsDupInternalRep,
     &VfsFreeInternalRep,
-    /* No internal to normalized, since we don't create any
-     * pure 'internal' Tcl_Obj path representations */
+    /* No internal to normalized, since we don't create
+     * any pure 'internal' Tcl_Obj path representations */
     NULL,
-    /* No create native rep function, since we don't use it
-     * and don't choose to support uses of 'Tcl_FSNewNativePath' */
+    /* No create native rep function, since we don't use
+     * it and don't choose to support uses of
+     * Tcl_FSNewNativePath */
     NULL,
-    /* Normalize path isn't needed - we assume paths only have
-     * one representation */
+    /* Normalize path isn't needed - we assume paths only
+     * have one representation */
     NULL,
     &VfsFilesystemPathType,
     &VfsFilesystemSeparator,
@@ -790,7 +793,8 @@ static Tcl_Filesystem vfsFilesystem = {
     &VfsOpenFileChannel,
     &VfsMatchInDirectory,
     &VfsUtime,
-    /* We choose not to support symbolic links inside our VFS's */
+    /* We choose not to support symbolic links inside our
+     * VFS's */
     NULL,
     &VfsListVolumes,
     &VfsFileAttrStrings,
@@ -799,48 +803,44 @@ static Tcl_Filesystem vfsFilesystem = {
     &VfsCreateDirectory,
     &VfsRemoveDirectory,
     &VfsDeleteFile,
-    /* No copy file - fallback will occur at Tcl level */
+    /* No copy file; use the core fallback mechanism */
     NULL,
-    /* No rename file - fallback will occur at Tcl level */
+    /* No rename file; use the core fallback mechanism */
     NULL,
-    /* No copy directory - fallback will occur at Tcl level */
+    /* No copy directory; use the core fallback mechanism */
     NULL,
     /* Core will use stat for lstat */
     NULL,
-    /* No load - fallback on core implementation */
+    /* No load; use the core fallback mechansism */
     NULL,
-    /* We don't need a getcwd or chdir - fallback on Tcl's versions */
+    /* We don't need a getcwd or chdir; the core's own
+     * internal value is suitable */
     NULL,
     NULL
 };
 .CE
+.SH "FILESYSTEM INFRASTRUCTURE"
 .PP
-Any functions which take path names in Tcl_Obj form take
-those names in UTF\-8 form.  The filesystem infrastructure API is
-designed to support efficient, cached conversion of these UTF\-8 paths
-to other native representations.
-.SH TYPENAME
+These fields contain basic information about the filesystem structure
+and addresses of functions which are used to associate
+a particular filesystem with a file path, and deal with the internal
+handling of path representations, for example copying and freeing such
+representations.
+.SS TYPENAME
 .PP
 The \fItypeName\fR field contains a null-terminated string that
 identifies the type of the filesystem implemented, e.g.
 ``native'' or ``zip'' or ```vfs''.
-.PP
-.SH "STRUCTURE LENGTH"
+.SS "STRUCTURE LENGTH"
 .PP
 The \fIstructureLength\fR field is generally implemented as
 \fIsizeof(Tcl_Filesystem)\fR, and is there to allow easier
 binary backwards compatibility if the size of the structure
 changes in a future Tcl release.
-.SH VERSION
+.SS VERSION
 .PP
 The \fIversion\fR field should be set to \fBTCL_FILESYSTEM_VERSION_1\fR.
-.SH "FILESYSTEM INFRASTRUCTURE"
-.PP
-These fields contain addresses of functions which are used to associate
-a particular filesystem with a file path, and deal with the internal
-handling of path representations, for example copying and freeing such
-representations.
-.SH PATHINFILESYSTEMPROC
+.SS PATHINFILESYSTEMPROC
 .PP
 The \fIpathInFilesystemProc\fR field contains the address of a function
 which is called to determine whether a given path object belongs to this
@@ -858,10 +858,10 @@ Tcl's internal list of known filesystems.
 .PP
 .CS
 typedef int Tcl_FSPathInFilesystemProc(
-	Tcl_Obj *\fIpathPtr\fR,
-	ClientData *\fIclientDataPtr\fR);
+        Tcl_Obj *\fIpathPtr\fR,
+        ClientData *\fIclientDataPtr\fR);
 .CE
-.SH DUPINTERNALREPPROC
+.SS DUPINTERNALREPPROC
 .PP
 This function makes a copy of a path's internal representation, and is
 called when Tcl needs to duplicate a path object.  If NULL, Tcl will
@@ -870,18 +870,18 @@ regenerated later.
 .PP
 .CS
 typedef ClientData Tcl_FSDupInternalRepProc(
-	ClientData \fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
-.SH FREEINTERNALREPPROC
+.SS FREEINTERNALREPPROC
 Free the internal representation.  This must be implemented if internal
 representations need freeing (i.e. if some memory is allocated when an
 internal representation is generated), but may otherwise be NULL.
 .PP
 .CS
 typedef void Tcl_FSFreeInternalRepProc(
-	ClientData \fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
-.SH INTERNALTONORMALIZEDPROC
+.SS INTERNALTONORMALIZEDPROC
 .PP
 Function to convert internal representation to a normalized path.  Only
 required if the filesystem creates pure path objects with no string/path
@@ -890,9 +890,9 @@ representation is the normalized path.
 .PP
 .CS
 typedef Tcl_Obj* Tcl_FSInternalToNormalizedProc(
-	ClientData \fIclientData\fR);
+        ClientData \fIclientData\fR);
 .CE
-.SH CREATEINTERNALREPPROC
+.SS CREATEINTERNALREPPROC
 .PP
 Function to take a path object, and calculate an internal
 representation for it, and store that native representation in the
@@ -902,9 +902,9 @@ immediately creates an internal representation for paths it accepts.
 .PP
 .CS
 typedef ClientData Tcl_FSCreateInternalRepProc(
-	Tcl_Obj *\fIpathPtr\fR);
+        Tcl_Obj *\fIpathPtr\fR);
 .CE
-.SH NORMALIZEPATHPROC
+.SS NORMALIZEPATHPROC
 .PP
 Function to normalize a path.  Should be implemented for all
 filesystems which can have multiple string representations for the same
@@ -929,9 +929,9 @@ up to and including the file separator is known and normalized.
 .PP
 .CS
 typedef int Tcl_FSNormalizePathProc(
-	Tcl_Interp *\fIinterp\fR,
-	Tcl_Obj *\fIpathPtr\fR,
-	int \fInextCheckpoint\fR);
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_Obj *\fIpathPtr\fR,
+        int \fInextCheckpoint\fR);
 .CE
 .SH "FILESYSTEM OPERATIONS"
 .PP
@@ -945,7 +945,7 @@ this may be desirable (for example, a read-only filesystem should not
 implement the last four functions, and a filesystem which does not
 support symbolic links need not implement the \fBreadlink\fR function,
 etc.  The Tcl core expects filesystems to behave in this way).
-.SH FILESYSTEMPATHTYPEPROC
+.SS FILESYSTEMPATHTYPEPROC
 .PP
 Function to determine the type of a path in this filesystem.  May be
 NULL, in which case no type information will be available to users of
@@ -958,9 +958,9 @@ to it.
 .PP
 .CS
 typedef Tcl_Obj* Tcl_FSFilesystemPathTypeProc(
-	Tcl_Obj *\fIpathPtr\fR);
+        Tcl_Obj *\fIpathPtr\fR);
 .CE
-.SH FILESYSTEMSEPARATORPROC
+.SS FILESYSTEMSEPARATORPROC
 .PP
 Function to return the separator character(s) for this filesystem.
 This need only be implemented if the filesystem wishes to use a
@@ -970,9 +970,9 @@ return value should be an object with refCount of zero.
 .PP
 .CS
 typedef Tcl_Obj* Tcl_FSFilesystemSeparatorProc(
-	Tcl_Obj *\fIpathPtr\fR);
+        Tcl_Obj *\fIpathPtr\fR);
 .CE
-.SH STATPROC
+.SS STATPROC
 .PP
 Function to process a \fBTcl_FSStat\fR call.  Must be implemented for any
 reasonable filesystem, since many Tcl level commands depend crucially
@@ -981,8 +981,8 @@ upon it (e.g. \fBfile atime\fR, \fBfile isdirectory\fR, \fBfile size\fR,
 .PP
 .CS
 typedef int Tcl_FSStatProc(
-	Tcl_Obj *\fIpathPtr\fR,
-	Tcl_StatBuf *\fIstatPtr\fR);
+        Tcl_Obj *\fIpathPtr\fR,
+        Tcl_StatBuf *\fIstatPtr\fR);
 .CE
 .PP
 The \fBTcl_FSStatProc\fR fills the stat structure \fIstatPtr\fR with
@@ -998,7 +998,7 @@ time.
 If the file represented by \fIpathPtr\fR exists, the
 \fBTcl_FSStatProc\fR returns 0 and the stat structure is filled with
 data.  Otherwise, -1 is returned, and no stat info is given.
-.SH ACCESSPROC
+.SS ACCESSPROC
 .PP
 Function to process a \fBTcl_FSAccess\fR call.  Must be implemented for
 any reasonable filesystem, since many Tcl level commands depend crucially
@@ -1006,8 +1006,8 @@ upon it (e.g. \fBfile exists\fR, \fBfile readable\fR).
 .PP
 .CS
 typedef int Tcl_FSAccessProc(
-	Tcl_Obj *\fIpathPtr\fR,
-	int \fImode\fR);
+        Tcl_Obj *\fIpathPtr\fR,
+        int \fImode\fR);
 .CE
 .PP
 The \fBTcl_FSAccessProc\fR checks whether the process would be allowed
@@ -1019,8 +1019,7 @@ permissions of the file referred by this symbolic link should be tested.
 On success (all requested permissions granted), zero is returned.  On
 error (at least one bit in mode asked for a permission that is denied,
 or some other  error occurred), -1 is returned.
-.PP
-.SH OPENFILECHANNELPROC
+.SS OPENFILECHANNELPROC
 .PP
 Function to process a \fBTcl_FSOpenFileChannel\fR call.  Must be
 implemented for any reasonable filesystem, since any operations
@@ -1029,10 +1028,10 @@ which require open or accessing a file's contents will use it
 .PP
 .CS
 typedef Tcl_Channel Tcl_FSOpenFileChannelProc(
-	Tcl_Interp *\fIinterp\fR,
-	Tcl_Obj *\fIpathPtr\fR,
-	int \fImode\fR,
-	int \fIpermissions\fR);
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_Obj *\fIpathPtr\fR,
+        int \fImode\fR,
+        int \fIpermissions\fR);
 .CE
 .PP
 The \fBTcl_FSOpenFileChannelProc\fR opens a file specified by
@@ -1053,7 +1052,7 @@ interpreter; to register it, use \fBTcl_RegisterChannel\fR. If one of
 the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
 previously closed, the act of creating the new channel also assigns it
 as a replacement for the standard channel.
-.SH MATCHINDIRECTORYPROC
+.SS MATCHINDIRECTORYPROC
 .PP
 Function to process a \fBTcl_FSMatchInDirectory\fR call.  If not
 implemented, then glob and recursive copy functionality will be lacking
@@ -1062,11 +1061,11 @@ which use glob functionality internally).
 .PP
 .CS
 typedef int Tcl_FSMatchInDirectoryProc(
-	Tcl_Interp* \fIinterp\fR,
-	Tcl_Obj *\fIresult\fR,
-	Tcl_Obj *\fIpathPtr\fR,
-	CONST char *\fIpattern\fR,
-	Tcl_GlobTypeData * \fItypes\fR);
+        Tcl_Interp* \fIinterp\fR,
+        Tcl_Obj *\fIresultPtr\fR,
+        Tcl_Obj *\fIpathPtr\fR,
+        CONST char *\fIpattern\fR,
+        Tcl_GlobTypeData *\fItypes\fR);
 .CE
 .PP
 The function should return all files or directories (or other filesystem
@@ -1082,28 +1081,28 @@ documented whether \fIpathPtr\fR will have a file separator at its end of
 not, so code should be flexible to both possibilities.
 .PP
 The return value is a standard Tcl result indicating whether an error
-occurred in the matching process.  Error messages are placed in \fIinterp\fR;
-on a \fBTCL_OK\fR result, the interpreter should not be modified, but
-rather results should be added to the \fIresult\fR object given
-(which can be assumed to be a valid Tcl list).  The matches added
-to \fIresult\fR should include any path prefix given in \fIpathPtr\fR
+occurred in the matching process.  Error messages are placed in
+\fIinterp\fR; on a \fBTCL_OK\fR result, results should be added to the
+\fIresultPtr\fR object given (which can be assumed to be a valid
+unshared Tcl list).  The matches added
+to \fIresultPtr\fR should include any path prefix given in \fIpathPtr\fR
 (this usually means they will be absolute path specifications).
 Note that if no matches are found, that simply leads to an empty
-result --- errors are only signaled for actual file or filesystem
+result; errors are only signaled for actual file or filesystem
 problems which may occur during the matching process.
 .PP
 The \fBTcl_GlobTypeData\fR structure passed in the \fItypes\fR 
 parameter contains the following fields:
 .CS
 typedef struct Tcl_GlobTypeData {
-	/* Corresponds to bcdpfls as in 'find -t' */
-	int \fItype\fR;
-	/* Corresponds to file permissions */
-	int \fIperm\fR;
-	/* Acceptable mac type */
-	Tcl_Obj *\fImacType\fR;
-	/* Acceptable mac creator */
-	Tcl_Obj *\fImacCreator\fR;
+        /* Corresponds to bcdpfls as in 'find -t' */
+        int \fItype\fR;
+        /* Corresponds to file permissions */
+        int \fIperm\fR;
+        /* Acceptable mac type */
+        Tcl_Obj *\fImacType\fR;
+        /* Acceptable mac creator */
+        Tcl_Obj *\fImacCreator\fR;
 } Tcl_GlobTypeData;
 .CE
 .PP
@@ -1119,7 +1118,7 @@ which lie within the given \fIpathPtr\fR (and in this case, \fIpathPtr\fR
 need not lie within the same filesystem - different to all other cases in
 which this function is called).  Support for this is critical if Tcl is
 to have seamless transitions between from one filesystem to another.
-.SH UTIMEPROC
+.SS UTIMEPROC
 .PP
 Function to process a \fBTcl_FSUtime\fR call.  Required to allow setting
 (not reading) of times with \fBfile mtime\fR, \fBfile atime\fR and the
@@ -1127,8 +1126,8 @@ open-r/open-w/fcopy implementation of \fBfile copy\fR.
 .PP
 .CS
 typedef int Tcl_FSUtimeProc(
-	Tcl_Obj *\fIpathPtr\fR,
-	struct utimbuf *\fItval\fR);
+        Tcl_Obj *\fIpathPtr\fR,
+        struct utimbuf *\fItval\fR);
 .CE
 .PP
 The access and modification times of the file specified by \fIpathPtr\fR
@@ -1136,16 +1135,16 @@ should be changed to the values given in the \fItval\fR structure.
 .PP
 The return value should be 0 on success and -1 on an error, as
 with the system \fButime\fR.
-.SH LINKPROC
+.SS LINKPROC
 .PP
 Function to process a \fBTcl_FSLink\fR call.  Should be implemented
 only if the filesystem supports links, and may otherwise be NULL.
 .PP
 .CS
 typedef Tcl_Obj* Tcl_FSLinkProc(
-	Tcl_Obj *\fIlinkNamePtr\fR,
-	Tcl_Obj *\fItoPtr\fR,
-	int \fIlinkAction\fR);
+        Tcl_Obj *\fIlinkNamePtr\fR,
+        Tcl_Obj *\fItoPtr\fR,
+        int \fIlinkAction\fR);
 .CE
 .PP
 If \fItoPtr\fR is NULL, the function is being asked to read the
@@ -1160,7 +1159,7 @@ and NULL otherwise.  In this case the result is not owned by the caller
 (i.e. no ref count manipulation on either end is needed). See
 the documentation for \fBTcl_FSLink\fR for the correct interpretation
 of the \fIlinkAction\fR flags.
-.SH LISTVOLUMESPROC
+.SS LISTVOLUMESPROC
 .PP
 Function to list any filesystem volumes added by this filesystem.
 Should be implemented only if the filesystem adds volumes at the head
@@ -1183,8 +1182,7 @@ to Tcl which will copy the contents and then decrement the count back
 to where it was).
 .PP
 Therefore, Tcl considers return values from this proc to be read-only.
-.PP
-.SH FILEATTRSTRINGSPROC
+.SS FILEATTRSTRINGSPROC
 .PP
 Function to list all attribute strings which are valid for this
 filesystem.  If not implemented the filesystem will not support
@@ -1195,8 +1193,8 @@ methods.
 .PP
 .CS
 typedef CONST char** Tcl_FSFileAttrStringsProc(
-	Tcl_Obj *\fIpathPtr\fR,
-	Tcl_Obj** \fIobjPtrRef\fR);
+        Tcl_Obj *\fIpathPtr\fR,
+        Tcl_Obj** \fIobjPtrRef\fR);
 .CE
 .PP
 The called function may either return an array of strings, or may
@@ -1207,17 +1205,17 @@ the list should be disposed of by Tcl when done, it should have a
 reference count of zero, and if the list should not be disposed of, the
 filesystem should ensure it returns an object with a refererence count
 of at least one.
-.SH FILEATTRSGETPROC
+.SS FILEATTRSGETPROC
 .PP
 Function to process a \fBTcl_FSFileAttrsGet\fR call, used by \fBfile
 attributes\fR.
 .PP
 .CS
 typedef int Tcl_FSFileAttrsGetProc(
-	Tcl_Interp *\fIinterp\fR,
-	int \fIindex\fR,
-	Tcl_Obj *\fIpathPtr\fR,
-	Tcl_Obj **\fIobjPtrRef\fR);
+        Tcl_Interp *\fIinterp\fR,
+        int \fIindex\fR,
+        Tcl_Obj *\fIpathPtr\fR,
+        Tcl_Obj **\fIobjPtrRef\fR);
 .CE
 .PP
 Returns a standard Tcl return code.  The attribute value retrieved,
@@ -1226,7 +1224,7 @@ the \fBTcl_FSFileAttrStringsProc\fR, is a Tcl_Obj placed in \fIobjPtrRef\fR (if
 \fBTCL_OK\fR was returned) and is likely to have a reference count of zero.  Either
 way we must either store it somewhere (e.g. the Tcl result), or
 Incr/Decr its reference count to ensure it is properly freed.
-.SH FILEATTRSSETPROC
+.SS FILEATTRSSETPROC
 .PP
 Function to process a \fBTcl_FSFileAttrsSet\fR call, used by \fBfile
 attributes\fR.  If the filesystem is read-only, there is no need
@@ -1234,38 +1232,38 @@ to implement this.
 .PP
 .CS
 typedef int Tcl_FSFileAttrsSetProc(
-	Tcl_Interp *\fIinterp\fR,
-	int \fIindex\fR,
-	Tcl_Obj *\fIpathPtr\fR,
-	Tcl_Obj *\fIobjPtr\fR);
+        Tcl_Interp *\fIinterp\fR,
+        int \fIindex\fR,
+        Tcl_Obj *\fIpathPtr\fR,
+        Tcl_Obj *\fIobjPtr\fR);
 .CE
 .PP
 The attribute value of the \fIindex\fR'th element in the list returned by
 the Tcl_FSFileAttrStringsProc should be set to the \fIobjPtr\fR given.
-.SH CREATEDIRECTORYPROC
+.SS CREATEDIRECTORYPROC
 .PP
 Function to process a \fBTcl_FSCreateDirectory\fR call.  Should be
 implemented unless the FS is read-only.
 .PP
 .CS
 typedef int Tcl_FSCreateDirectoryProc(
-	Tcl_Obj *\fIpathPtr\fR);
+        Tcl_Obj *\fIpathPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
 occurred in the process.  If successful, a new directory should have
 been added to the filesystem in the location specified by
 \fIpathPtr\fR.
-.SH REMOVEDIRECTORYPROC
+.SS REMOVEDIRECTORYPROC
 .PP
 Function to process a \fBTcl_FSRemoveDirectory\fR call.  Should be
 implemented unless the FS is read-only.
 .PP
 .CS
 typedef int Tcl_FSRemoveDirectoryProc(
-	Tcl_Obj *\fIpathPtr\fR,
-	int \fIrecursive\fR,
-	Tcl_Obj **\fIerrorPtr\fR);
+        Tcl_Obj *\fIpathPtr\fR,
+        int \fIrecursive\fR,
+        Tcl_Obj **\fIerrorPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
@@ -1276,14 +1274,14 @@ deleted without error.  If this flag is not given, then and the
 directory is non-empty a POSIX 'EEXIST' error should be signalled.  If an
 error does occur, the name of the file or directory which caused the
 error should be placed in \fIerrorPtr\fR.
-.SH DELETEFILEPROC
+.SS DELETEFILEPROC
 .PP
 Function to process a \fBTcl_FSDeleteFile\fR call.  Should be implemented
 unless the FS is read-only.
 .PP
 .CS
 typedef int Tcl_FSDeleteFileProc(
-	Tcl_Obj *\fIpathPtr\fR);
+        Tcl_Obj *\fIpathPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
@@ -1294,7 +1292,10 @@ function and not Tcl_FSRemoveDirectoryProc when needed to delete them
 (even if they are symbolic links to directories).
 .SH "FILESYSTEM EFFICIENCY"
 .PP
-.SH LSTATPROC
+These functions need not be implemented for a particular filesystem
+because the core has a fallback implementation available. See each
+individual description for the consequences of leaving the field NULL.
+.SS LSTATPROC
 .PP
 Function to process a \fBTcl_FSLstat\fR call.  If not implemented, Tcl
 will attempt to use the \fIstatProc\fR defined above instead.  Therefore
@@ -1303,16 +1304,15 @@ it need only be implemented if a filesystem can differentiate between
 .PP
 .CS
 typedef int Tcl_FSLstatProc(
-	Tcl_Obj *\fIpathPtr\fR,
-	Tcl_StatBuf *\fIstatPtr\fR);
+        Tcl_Obj *\fIpathPtr\fR,
+        Tcl_StatBuf *\fIstatPtr\fR);
 .CE
 .PP
 The behavior of this function is very similar to that of the
 \fBTcl_FSStatProc\fR defined above, except that if it is applied
 to a symbolic link, it returns information about the link, not
 about the target file.
-.PP
-.SH COPYFILEPROC
+.SS COPYFILEPROC
 .PP
 Function to process a \fBTcl_FSCopyFile\fR call.  If not implemented Tcl
 will fall back on \fBopen\fR-r, \fBopen\fR-w and \fBfcopy\fR as a
@@ -1322,8 +1322,8 @@ that action more efficiently.
 .PP
 .CS
 typedef int Tcl_FSCopyFileProc(
-	Tcl_Obj *\fIsrcPathPtr\fR,
-	Tcl_Obj *\fIdestPathPtr\fR);
+        Tcl_Obj *\fIsrcPathPtr\fR,
+        Tcl_Obj *\fIdestPathPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
@@ -1338,7 +1338,7 @@ function and not \fIcopyDirectoryProc\fR when needed to copy them
 filesystem determines it cannot support the \fBfile copy\fR action,
 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
 result will tell Tcl to use its standard fallback mechanisms.
-.SH RENAMEFILEPROC
+.SS RENAMEFILEPROC
 .PP
 Function to process a \fBTcl_FSRenameFile\fR call.  If not implemented,
 Tcl will fall back on a copy and delete mechanism.  Therefore it need
@@ -1347,8 +1347,8 @@ efficiently.
 .PP
 .CS
 typedef int Tcl_FSRenameFileProc(
-	Tcl_Obj *\fIsrcPathPtr\fR,
-	Tcl_Obj *\fIdestPathPtr\fR);
+        Tcl_Obj *\fIsrcPathPtr\fR,
+        Tcl_Obj *\fIdestPathPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
@@ -1356,7 +1356,7 @@ occurred in the renaming process.  If the
 filesystem determines it cannot support the \fBfile rename\fR action,
 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
 result will tell Tcl to use its standard fallback mechanisms.
-.SH COPYDIRECTORYPROC
+.SS COPYDIRECTORYPROC
 .PP
 Function to process a \fBTcl_FSCopyDirectory\fR call.  If not
 implemented, Tcl will fall back on a recursive \fBfile mkdir\fR, \fBfile copy\fR
@@ -1365,9 +1365,9 @@ perform that action more efficiently.
 .PP
 .CS
 typedef int Tcl_FSCopyDirectoryProc(
-	Tcl_Obj *\fIsrcPathPtr\fR,
-	Tcl_Obj *\fIdestPathPtr\fR,
-	Tcl_Obj **\fIerrorPtr\fR);
+        Tcl_Obj *\fIsrcPathPtr\fR,
+        Tcl_Obj *\fIdestPathPtr\fR,
+        Tcl_Obj **\fIerrorPtr\fR);
 .CE
 .PP
 The return value is a standard Tcl result indicating whether an error
@@ -1381,7 +1381,7 @@ than the Tcl level \fBfile copy\fR subcommand).  Finally, if the
 filesystem determines it cannot support the directory copy action,
 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
 result will tell Tcl to use its standard fallback mechanisms.
-.SH LOADFILEPROC
+.SS LOADFILEPROC
 .PP
 Function to process a \fBTcl_FSLoadFile\fR call.  If not implemented, Tcl
 will fall back on a copy to native-temp followed by a \fBTcl_FSLoadFile\fR on
@@ -1392,10 +1392,10 @@ entirely.
 .PP
 .CS
 typedef int Tcl_FSLoadFileProc(
-	Tcl_Interp *\fIinterp\fR,
-	Tcl_Obj *\fIpathPtr\fR,
-	Tcl_LoadHandle *\fIhandlePtr\fR,
-	Tcl_FSUnloadFileProc *\fIunloadProcPtr\fR);
+        Tcl_Interp *\fIinterp\fR,
+        Tcl_Obj *\fIpathPtr\fR,
+        Tcl_LoadHandle *\fIhandlePtr\fR,
+        Tcl_FSUnloadFileProc *\fIunloadProcPtr\fR);
 .CE
 .PP
 Returns a standard Tcl completion code.  If an error occurs, an error
@@ -1412,7 +1412,7 @@ in the new code.  Each filesystem is free to define the
 filesystem determines it cannot support the file load action,
 calling \fBTcl_SetErrno(EXDEV)\fR and returning a non-\fBTCL_OK\fR
 result will tell Tcl to use its standard fallback mechanisms.
-.SH UNLOADFILEPROC	    
+.SS UNLOADFILEPROC
 .PP
 Function to unload a previously successfully loaded file.  If load was
 implemented, then this should also be implemented, if there is any
@@ -1420,9 +1420,9 @@ cleanup action required.
 .PP
 .CS
 typedef void Tcl_FSUnloadFileProc(
-	Tcl_LoadHandle \fIloadHandle\fR);
+        Tcl_LoadHandle \fIloadHandle\fR);
 .CE
-.SH GETCWDPROC     
+.SS GETCWDPROC     
 .PP
 Function to process a \fBTcl_FSGetCwd\fR call.  Most filesystems need not
 implement this.  It will usually only be called once, if \fBgetcwd\fR is
@@ -1430,7 +1430,7 @@ called before \fBchdir\fR.  May be NULL.
 .PP
 .CS
 typedef Tcl_Obj* Tcl_FSGetCwdProc(
-	Tcl_Interp *\fIinterp\fR);
+        Tcl_Interp *\fIinterp\fR);
 .CE
 .PP
 If the filesystem supports a native notion of a current working
@@ -1439,8 +1439,7 @@ function should return that cwd as the result, or NULL if the current
 directory could not be determined (e.g. the user does not have
 appropriate permissions on the cwd directory).  If NULL is returned, an
 error message is left in the \fIinterp\fR's result.
-.PP
-.SH CHDIRPROC	    
+.SS CHDIRPROC
 .PP
 Function to process a \fBTcl_FSChdir\fR call.  If filesystems do not
 implement this, it will be emulated by a series of directory access
@@ -1454,7 +1453,7 @@ correct system \fBchdir\fR API).
 .PP
 .CS
 typedef int Tcl_FSChdirProc(
-	Tcl_Obj *\fIpathPtr\fR);
+        Tcl_Obj *\fIpathPtr\fR);
 .CE
 .PP
 The \fBTcl_FSChdirProc\fR changes the applications current working