Make pub publish more user friendly:

utils/pub/path.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /// A comprehensive, cross-platform path manipulation library.
 library path;
 
 import 'dart:io' as io;
 
 /// An internal builder for the current OS so we can provide a straight
@@ skipping 84 matching lines @@
 ///
 /// If a part is an absolute path, then anything before that will be ignored:
 ///
 ///     path.join('path', '/to', 'foo'); // -> '/to/foo'
 String join(String part1, [String part2, String part3, String part4,
             String part5, String part6, String part7, String part8]) =>
   _builder.join(part1, part2, part3, part4, part5, part6, part7, part8);
 
 // TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed.
 /// Splits [path] into its components using the current platform's [separator].
-/// Example:
 ///
 ///     path.split('path/to/foo'); // -> ['path', 'to', 'foo']
 ///
+/// The path will *not* be normalized before splitting.
+///
+///     path.split('path/../foo'); // -> ['path', '..', 'foo']
+///
 /// If [path] is absolute, the root directory will be the first element in the
 /// array. Example:
 ///
 ///     // Unix
 ///     path.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo']
 ///
 ///     // Windows
 ///     path.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo']
 List<String> split(String path) => _builder.split(path);
 
@@ skipping 189 matching lines @@
 
     return buffer.toString();
   }
 
   // TODO(nweiz): add a UNC example for Windows once issue 7323 is fixed.
   /// Splits [path] into its components using the current platform's
   /// [separator]. Example:
   ///
   ///     builder.split('path/to/foo'); // -> ['path', 'to', 'foo']
   ///
+  /// The path will *not* be normalized before splitting.
+  ///
+  ///     builder.split('path/../foo'); // -> ['path', '..', 'foo']
+  ///
   /// If [path] is absolute, the root directory will be the first element in the
   /// array. Example:
   ///
   ///     // Unix
   ///     builder.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo']
   ///
   ///     // Windows
   ///     builder.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo']
   List<String> split(String path) {
     var parsed = _parse(path);
@@ skipping 307 matching lines @@
 
     var lastDot = file.lastIndexOf('.');
 
     // If there is no dot, or it's the first character, like '.bashrc', it
     // doesn't count.
     if (lastDot <= 0) return [file, ''];
 
     return [file.substring(0, lastDot), file.substring(lastDot)];
   }
 }