Clarify docs a little

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@27019 72102866-910b-0410-8b05-ffd578937521

Documentation/Base.gsdoc

@@ -213,7 +213,7 @@ notice and this notice are preserved.
 		which contain characters not legal in XML.  GNUstep always
 		generates legal XML, at the cost of a certain degree of
 		compatibility.  GNUstep XML property lists use a backslash
-		to escape illegal chatracters, and consequently any string
+		to escape illegal characters, and consequently any string
 		containing either a backslash or an illegal character will
 		be written differently to the same string on MacOS-X.
 	      </p>
@@ -513,7 +513,8 @@ notice and this notice are preserved.
 	    <deflist>
 	      <term>GNUSTEP_SYSTEM_ROOT</term>
 	      <desc>
-		Obsolete.  Used to specify the GNUstep system root directory ... all
+		Obsolete.
+		Used to specify the GNUstep system root directory ... all
 		system libraries, tools, applications, headers, resources
 		in general are located relative to this.
 	      </desc>
@@ -538,7 +539,8 @@ notice and this notice are preserved.
 	  </p>
 	  <deflist>
 	    <term>GNUSTEP_USER_DIR</term>
-	    <desc>Obsolete.  Path for user specific GNUstep resources (eg. 'GNUstep').
+	    <desc>Obsolete.
+	    Path for user specific GNUstep resources (eg. 'GNUstep').
 	    Relative to the user's home directory.
 	    </desc>
 	    <term>GNUSTEP_USER_CONFIG_FILE</term>

Headers/Foundation/NSString.h

@@ -20,7 +20,35 @@
    License along with this library; if not, write to the Free
    Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02111 USA.
-   */ 
+  */
+
+/**
+<chapter>
+ <heading>Portable path handling</heading>
+ <p>Portable path handling (across both unix-like and mswindows operating
+ systems) requires some care.  A modern operating system uses the concept
+ of a single root to the filesystem, but mswindows has multiple filesystems
+ with no common root, so code must be aware of this.  There is also the
+ more minor issue that windows uses a backslash as a separator between
+ the components of a path and unix-like systems use a forward slash.
+ </p>
+ <p>GNUstep has three path handling modes, 'gnustep', 'unix', and 'windows'.
+ You should probably stick to using the default 'gnustep' mode in which the
+ path handling methods cope with both unix and windows style paths in
+ portable and tolerant manner:<br />
+ Paths are read in literally so they can be in the native format provided
+ by the operating system or in a non-native format.<br />
+ Paths are written out using the native format of the system the application
+ is running on (eg on windows slashes are converted to backslashes).<br />
+ The path handling methods accept either a forward or backward slash as a
+ path separator when parsing any path.<br />
+ The path handling methods add forward slashes when building new paths
+ internally or when standardising paths, so those path strings provide
+ a portable representation (as long as they are relative paths, not including
+ system specific roots).
+ </p>
+</chapter>
+ */ 
 
 #ifndef __NSString_h_GNUSTEP_BASE_INCLUDE
 #define __NSString_h_GNUSTEP_BASE_INCLUDE
@@ -594,7 +622,8 @@ typedef NSUInteger NSStringEncodingConversionOptions;
  * In windows mode a drive specification (eg C:) followed by a slash or
  * backslash, is an absolute path, as is any path beginning with a tilde.<br />
  * In any mode a UNC path (//host/share...) is always absolute.<br />
- * In gnustep path handling mode, the rules are the same as for windows,
+ * In the default gnustep path handling mode,
+ * the rules are the same as for windows,
  * except that a path whose root is a slash denotes an absolute path
  * when running on unix and a relative path when running under windows.
  */

Source/NSFileHandle.m

@@ -250,8 +250,9 @@ static Class NSFileHandle_ssl_class = nil;
 }
 
 /**
- *  Reads up to maximum unsigned int bytes from file or communications
- *  channel into return data.
+ * Reads up to maximum unsigned int bytes from file or communications
+ * channel into return data.<br />
+ * If the file is empty, returns an empty data item.
  */
 - (NSData*) readDataToEndOfFile
 {

Source/NSString.m

@@ -337,8 +337,13 @@ pathSepString()
 }
 
 /*
- * Find end of 'root' sequence in a string.  Characters before this
+ * Find the end of 'root' sequence in a string.  Characters before this
  * point in the string cannot be split into path components/extensions.
+ * This usage of the term 'root' is slightly different from the usual in
+ * that it includes the first part of any relative path.  The more normal
+ * usage of 'root' elsewhere is to indicate the first part of an absolute
+ * path.
+
  * Possible roots are -
  *
  * '/'			absolute root on unix
@@ -1528,20 +1533,20 @@ handle_printf_atsign (FILE *stream,
  * returned.  If string begins or ends with separator, empty strings will
  * be returned for those positions.</p>
  */
-- (NSArray *) componentsSeparatedByCharactersInSet: (NSCharacterSet *)set
+- (NSArray *) componentsSeparatedByCharactersInSet: (NSCharacterSet *)separator
 {
   NSRange	search;
   NSRange	complete;
   NSRange	found;
   NSMutableArray *array;
 
-  if (set == nil)
-    [NSException raise: NSInvalidArgumentException format: @"set is nil"];
+  if (separator == nil)
+    [NSException raise: NSInvalidArgumentException format: @"separator is nil"];
 
   array = [NSMutableArray array];
   search = NSMakeRange (0, [self length]);
   complete = search;
-  found = [self rangeOfCharacterFromSet: set];
+  found = [self rangeOfCharacterFromSet: separator];
   while (found.length != 0)
     {
       NSRange current;
@@ -1552,7 +1557,7 @@ handle_printf_atsign (FILE *stream,
 
       search = NSMakeRange (found.location + found.length,
 	complete.length - found.location - found.length);
-      found = [self rangeOfCharacterFromSet: set
+      found = [self rangeOfCharacterFromSet: separator
                                     options: 0
                                       range: search];
     }

Testing/nsfilehandle.m

@@ -27,16 +27,20 @@ main ()
 
   pool = [[NSAutoreleasePool alloc] init];
 
-  src = [[NSFileHandle fileHandleForReadingAtPath:@"nsfilehandle.m"] retain];
-  assert(src != nil);
   dst = [[NSFileHandle fileHandleForWritingAtPath:@"nsfilehandle.dat"] retain];
   if (dst == nil)
     {
       creat("nsfilehandle.dat", 0644);
       dst = [[NSFileHandle fileHandleForWritingAtPath:@"nsfilehandle.dat"] retain];
+      src = [NSFileHandle fileHandleForReadingAtPath:@"nsfilehandle.dat"];
+      NSLog(@"%@", [src readDataToEndOfFile]);
     }
   assert(dst != nil);
 
+  src = [[NSFileHandle fileHandleForReadingAtPath:@"nsfilehandle.m"] retain];
+  assert(src != nil);
+
+  assert(src != nil);
   d0 = [[src readDataToEndOfFile] retain];
   [(NSFileHandle*)dst writeData: d0];
   [src release];