Merge pull request #1887 from zevaverbach/patch-1

enumerates the states in which code is executed...

docs/appcontext.rst

@@ -5,31 +5,37 @@ The Application Context
 
 .. versionadded:: 0.9
 
-One of the design ideas behind Flask is that there are two different
+One of the design ideas behind Flask is that there are at least two 
-“states” in which code is executed.  The application setup state in which
+different “states” in which code is executed:
-the application implicitly is on the module level.  It starts when the
+
-:class:`Flask` object is instantiated, and it implicitly ends when the
+1.  The application setup state, in which the application implicitly is 
-first request comes in.  While the application is in this state a few
+on the module level.  
-assumptions are true:
+
-
+    This state starts when the :class:`Flask` object is instantiated, and 
--   the programmer can modify the application object safely.
+    it implicitly ends when the first request comes in.  While the 
--   no request handling happened so far
+    application is in this state, a few assumptions are true:
--   you have to have a reference to the application object in order to
+
-    modify it, there is no magic proxy that can give you a reference to
+    -   the programmer can modify the application object safely.
-    the application object you're currently creating or modifying.
+    -   no request handling happened so far
-
+    -   you have to have a reference to the application object in order to
-In contrast, during request handling, a couple of other rules exist:
+        modify it, there is no magic proxy that can give you a reference to
-
+        the application object you're currently creating or modifying.
--   while a request is active, the context local objects
+
+2.  In contrast, in the request handling state, a couple of other rules 
+exist:
+
+    -   while a request is active, the context local objects
     (:data:`flask.request` and others) point to the current request.
--   any code can get hold of these objects at any time.
+    -   any code can get hold of these objects at any time.
-
+
-There is a third state which is sitting in between a little bit.
+3.  There is also a third state somewhere in between 'module-level' and 
-Sometimes you are dealing with an application in a way that is similar to
+'request-handling':
-how you interact with applications during request handling; just that there
+
-is no request active.  Consider, for instance, that you're sitting in an
+    Sometimes you are dealing with an application in a way that is similar to
-interactive Python shell and interacting with the application, or a
+    how you interact with applications during request handling, but without 
-command line application.
+    there being an active request.  Consider, for instance, that you're 
+    sitting in an interactive Python shell and interacting with the 
+    application, or a command line application.
 
 The application context is what powers the :data:`~flask.current_app`
 context local.