fix

1 files changed, 18 insertions, 10 deletions

diff --git a/docs/narr/advconfig.rst b/docs/narr/advconfig.rst
index a4692e4c6..2ed0a96ab 100644
--- a/docs/narr/advconfig.rst
+++ b/docs/narr/advconfig.rst
@@ -164,8 +164,9 @@ Using ``config.commit()``
 
 You can manually commit a configuration by using the
 :meth:`pyramid.config.Configurator.commit` method between configuration
-calls.  For example, we can make the application we examined previously which
-generated a conflict exception
+calls.  For example, we prevent conflicts from occurring in the application
+we examined previously as the result of adding a ``commit``.  Here's the
+application that generates conflicts:
 
 .. code-block:: python
    :linenos:
@@ -229,6 +230,10 @@ Calling :meth:`~pyramid.config.Configurator.commit` is safe at any time.  It
 executes all pending configuration actions and leaves the configuration
 action list "clean".
 
+Note that :meth:`~pyramid.config.Configurator.commit` has no effect when
+you're using an *autocommitting* configurator (see
+:ref:`autocommitting_configurator`).
+
 .. _autocommitting_configurator:
 
 Using An Autocommitting Configurator
@@ -246,9 +251,12 @@ configurator constructor parameter: ``autocommit=True``.  For example:
        config = Configurator(autocommit=True)
 
 When the ``autocommit`` parameter passed to the Configurator is ``True``,
-conflict detection (and :ref:`twophase_config`) is disabled.
+conflict detection (and :ref:`twophase_config`) is disabled.  Configuration
+statements will be executed immediately, and succeeding statements will
+override preceding ones.
+
 :meth:`pyramid.config.Configurator.commit` has no effect when ``autocommit``
-is ``True`` either.
+is ``True``.
 
 If you use a Configurator in code that performs unit testing, it's usually a
 good idea to use an autocommitting Configurator, because you are usually
@@ -267,12 +275,12 @@ the "include" method.  See also
 
 Automatic conflict resolution supports this goal: if a user wants to reuse a
 Pyramid application, and they want to customize the configuration of this
-application without hacking its code "from outside", they can "include" the
-package and override only some of its configuration statements within the
-code that does the include.  No conflicts will be generated by configuration
-statements within the code which does the including, even if configuration
-statements in the included code would conflict if it was moved "up" to the
-calling code.
+application without hacking its code "from outside", they can "include" a
+configuration function from the package and override only some of its
+configuration statements within the code that does the include.  No conflicts
+will be generated by configuration statements within the code which does the
+including, even if configuration statements in the included code would
+conflict if it was moved "up" to the calling code.
 
 Methods Which Provide Conflict Detection
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~