Merged revisions 68167,68276,68292-68293,68344 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r68167 | vinay.sajip | 2009-01-02 12:53:04 -0600 (Fri, 02 Jan 2009) | 1 line

  Minor documentation changes relating to NullHandler, the module used for handlers and references to ConfigParser.
........
  r68276 | tarek.ziade | 2009-01-03 18:04:49 -0600 (Sat, 03 Jan 2009) | 1 line

  fixed #1702551: distutils sdist was not pruning VCS directories under win32
........
  r68292 | skip.montanaro | 2009-01-04 04:36:58 -0600 (Sun, 04 Jan 2009) | 3 lines

  If user configures --without-gcc give preference to $CC instead of blindly
  assuming the compiler will be "cc".
........
  r68293 | tarek.ziade | 2009-01-04 04:37:52 -0600 (Sun, 04 Jan 2009) | 1 line

  using clearer syntax
........
  r68344 | marc-andre.lemburg | 2009-01-05 13:43:35 -0600 (Mon, 05 Jan 2009) | 7 lines

  Fix #4846 (Py_UNICODE_ISSPACE causes linker error) by moving the declaration
  into the extern "C" section.

  Add a few more comments and apply some minor edits to make the file contents
  fit the original structure again.
........
diff --git a/Include/unicodeobject.h b/Include/unicodeobject.h
index e6df277..8259743 100644
--- a/Include/unicodeobject.h
+++ b/Include/unicodeobject.h
@@ -126,6 +126,10 @@
 typedef unsigned long Py_UCS4; 
 #endif
 
+/* Py_UNICODE is the native Unicode storage format (code unit) used by
+   Python and represents a single Unicode element in the Unicode
+   type. */
+
 typedef PY_UNICODE_TYPE Py_UNICODE;
 
 /* --- UCS-2/UCS-4 Name Mangling ------------------------------------------ */
@@ -369,12 +373,12 @@
 
 #else
 
-/* Since splitting on whitespace is an important use case, and whitespace
-   in most situations is solely ASCII whitespace, we optimize for the common
-   case by using a quick look-up table with an inlined check.
- */
-PyAPI_DATA(const unsigned char) _Py_ascii_whitespace[];
+/* Since splitting on whitespace is an important use case, and
+   whitespace in most situations is solely ASCII whitespace, we
+   optimize for the common case by using a quick look-up table
+   _Py_ascii_whitespace (see below) with an inlined check.
 
+ */
 #define Py_UNICODE_ISSPACE(ch) \
 	((ch) < 128U ? _Py_ascii_whitespace[(ch)] : _PyUnicode_IsWhitespace(ch))
 
@@ -409,13 +413,14 @@
 #define Py_UNICODE_COPY(target, source, length)				\
 	Py_MEMCPY((target), (source), (length)*sizeof(Py_UNICODE))
 
-#define Py_UNICODE_FILL(target, value, length) do\
-    {Py_ssize_t i_; Py_UNICODE *t_ = (target); Py_UNICODE v_ = (value);\
+#define Py_UNICODE_FILL(target, value, length) \
+    do {Py_ssize_t i_; Py_UNICODE *t_ = (target); Py_UNICODE v_ = (value);\
         for (i_ = 0; i_ < (length); i_++) t_[i_] = v_;\
     } while (0)
 
-/* check if substring matches at given offset.  the offset must be
+/* Check if substring matches at given offset.  the offset must be
    valid, and the substring must not be empty */
+
 #define Py_UNICODE_MATCH(string, offset, substring) \
     ((*((string)->str + (offset)) == *((substring)->str)) && \
     ((*((string)->str + (offset) + (substring)->length-1) == *((substring)->str + (substring)->length-1))) && \
@@ -425,8 +430,6 @@
 extern "C" {
 #endif
 
-PyAPI_FUNC(int) PyUnicode_ClearFreeList(void);
-
 /* --- Unicode Type ------------------------------------------------------- */
 
 typedef struct {
@@ -641,6 +644,17 @@
 
 PyAPI_FUNC(PyObject*) PyUnicode_FromOrdinal(int ordinal);
 
+/* --- Free-list management ----------------------------------------------- */
+
+/* Clear the free list used by the Unicode implementation.
+
+   This can be used to release memory used for objects on the free
+   list back to the Python memory allocator.
+
+*/
+
+PyAPI_FUNC(int) PyUnicode_ClearFreeList(void);
+
 /* === Builtin Codecs ===================================================== 
 
    Many of these APIs take two arguments encoding and errors. These
@@ -1477,6 +1491,10 @@
 
 /* === Characters Type APIs =============================================== */
 
+/* Helper array used by Py_UNICODE_ISSPACE(). */
+
+PyAPI_DATA(const unsigned char) _Py_ascii_whitespace[];
+
 /* These should not be used directly. Use the Py_UNICODE_IS* and
    Py_UNICODE_TO* macros instead.