Index: Doc/library/configparser.rst
===================================================================
--- Doc/library/configparser.rst	(revision 74084)
+++ Doc/library/configparser.rst	(working copy)
@@ -94,6 +94,11 @@
    option names to lower case), the values ``foo %(bar)s`` and ``foo %(BAR)s`` are
    equivalent.
 
+   .. note::
+
+      This class should not be used by new applications; use `SafeConfigParser`
+      instead.
+
    .. versionadded:: 2.3
 
    .. versionchanged:: 2.6
@@ -107,11 +112,21 @@
 
    Derived class of :class:`ConfigParser` that implements a more-sane variant of
    the magical interpolation feature.  This implementation is more predictable as
-   well. New applications should prefer this version if they don't need to be
+   well.  For example, in `SafeConfigParser` you can escape format strings in
+   in the usual way::
+
+       [foo]
+       bar = %%(bing)s
+
+   This results in *bar* having the literal value '%(bing)s'.  `ConfigParser`,
+   on the other hand, will attempt to do the substitution despite the escape.
+
+   .. XXX Presumably there are other differences, and it would be good to add
+      notes about them here.
+
+   Applications should prefer `SafeConfigParser` unless they have a need to be
    compatible with older versions of Python.
 
-   .. XXX Need to explain what's safer/more predictable about it.
-
    .. versionadded:: 2.3
 
    .. versionchanged:: 2.6