reply to comments

story645 · story645 · commit e7a4fc30cb5e · 2020-05-27T22:05:34.000-04:00
diff --git a/doc/users/interactive.rst b/doc/users/interactive.rst
@@ -17,18 +17,18 @@ Matplotlib ships with :ref:`backends <what-is-a-backend>` binding to
 several GUI toolkits (Qt, Tk, Wx, GTK, macOS, JavaScript) and third party
 packages provide bindings to `kivy
 <https://github.com/kivy-garden/garden.matplotlib>`__ and `Jupyter Lab
-<https://github.com/matplotlib/ipympl>`__.  For the figures to be interactive, 
-the GUI event loop will need to be integrated with your interactive prompt. 
-We recommend using IPython (see :ref:`below <ipython-pylab>`).
+<https://github.com/matplotlib/ipympl>`__.  For the figures to be responsive to 
+mouse, keyboard, and critical paint events, the GUI event loop needs to be integrated 
+with an interactive prompt. We recommend using IPython (see :ref:`below <ipython-pylab>`).
 
 The `.pyplot` module provides functions for explicitly creating figures 
 that include interactive tools, a toolbar, a tool-tip, and
 :ref:`key bindings <key-event-handling>`:
 
-* `.pyplot.figure`
+`.pyplot.figure`
     Creates a new empty `.figure.Figure` or selects an existing figure
 
-* `.pyplot.subplots`
+`.pyplot.subplots`
     Creates a new `.figure.Figure` and fills it with a grid of `.axes.Axes`
 
 `.pyplot` has a notion of "The Current Figure" which can be accessed
@@ -38,9 +38,9 @@ through the current `.Figure` / `.axes.Axes` (or create one) as
 appropriate.  
 
 Matplotlib keeps a reference to all of the open figures
-created this way so they will not be garbage collected.  You can close
-and deregister `.Figure`\s from `.pyplot` individually via
-`.pyplot.close` or close all open figures via ``plt.close('all')``.
+created via `pyplot.figure` or `pyplot.subplots` so that the figures will not be garbage 
+collected. `.Figure`\s can be closed and deregistered from `.pyplot` individually via
+`.pyplot.close`; all open `.Figure`\s can be closed via ``plt.close('all')``.
 
 
 For more discussion of Matplotlib's event system and integrated event loops, please read:
@@ -58,12 +58,14 @@ IPython integration
 ===================
 
 We recommend using IPython for an interactive shell.  In addition to
-all of its features (improved tab-completion, magics,
-multiline editing, etc), it also ensures that the GUI toolkit event
-loop is properly integrated with the command line (see
-:ref:`cp_integration`).  To configure the integration and enable
-:ref:`interactive mode <controlling-interactive>` use the
-``%matplotlib`` magic
+all of its features (improved tab-completion, magics, multiline editing, etc), 
+it also ensures that the GUI toolkit event loop is properly integrated 
+with the command line (see :ref:`cp_integration`). 
+
+In this example, we are modifying a figure via an IPython prompt. 
+The figure is displayed in a `Qt5Agg` GUI Window. To configure the integration 
+and enable :ref:`interactive mode <controlling-interactive>` use the
+``%matplotlib`` magic:
 
 .. highlight:: ipython
 
@@ -98,7 +100,7 @@ If you wish to disable interactive modification of the plot:
 
    In [6]: plt.ioff()
 
-If you wish to re-enable interactive "live" modification of the plot:
+If you wish to re-enable interactive modification of the plot:
 
 ::
 
@@ -139,19 +141,22 @@ Interactive mode controls:
 
 - whether created figures are automatically shown
 - whether changes to artists automatically trigger re-drawing existing figures
-- when `.pyplot.show` exits: immediately, or after all of the figures have been closed if given no arguments
+- when `.pyplot.show()` returns: immediately, or after all of the figures have been closed when given no arguments
 
 If in interactive mode:
 
 - newly created figures will be displayed immediately
 - figures will automatically redraw when elements are changed
-- `pyplot.show` displays the figures and immediately returns to the prompt
+- `pyplot.show()` displays the figures and immediately returns
 
 If not in interactive mode:
 
 - newly created figures and changes to figures are not displayed until 
-`.pyplot.show` is called again or `.pyplot.pause` exits
-- `pyplot.show` runs the GUI event loop and does not return until all 
+   * `.pyplot.show()` returns and is called again
+   * `.pyplot.pause()` returns
+   * ` fig.canvas.flush_events` is called
+
+- `pyplot.show()` runs the GUI event loop and does not return until all 
 the plot windows are closed
 
 
@@ -161,21 +166,21 @@ to display the windows on your screen.  If you only want to run the
 GUI event loop for a fixed amount of time, you can use `.pyplot.pause`.
 This will block the progress of your code as if you had called
 `time.sleep`, ensure the current window is shown and re-drawn if needed, 
-and run the GUI event loop (so the windows are "live" for
-interactive modification) for the specified period of time.
+and run the GUI event loop for the specified period of time.
 
 The GUI event loop being integrated with your command prompt and 
 the figures being in interactive mode are independent of each other. 
 If you use `pyplot.ion` but have not arranged for the event loop integration, 
-your figures will appear but will not be "live" while the prompt is waiting for input. 
+your figures will appear but will not be interactive while the prompt is waiting for input. 
 You will not be able to pan/zoom and the figure may not even render
 (the window might appear black, transparent, or as a snapshot of the
 desktop under it).  Conversely, if you configure the event loop
-integration, displayed figures will be "live" while waiting for input
+integration, displayed figures will be responsive while waiting for input
 at the prompt, regardless of pyplot's "interactive mode". 
 
-The figures will also be "live" if you use ``pyplot.show(block=True)``, 
-`.pyplot.pause`, or run the the GUI main loop in some other way.
+No matter what combination of interactive mode setting and event loop integration, 
+figures will be responsive if you use ``pyplot.show(block=True)``, `.pyplot.pause`, or run 
+the GUI main loop in some other way.
 
 
 .. warning::
@@ -276,7 +281,7 @@ If you only need to use the classic notebook, you can use
 
   %matplotlib notebook
 
-which uses the `.backend_nbagg` backend which is installed by Matplotlib; 
+which uses the `.backend_nbagg` backend provided by Matplotlib; 
 however, nbagg does not work in Jupyter Lab.
 
 GUIs + Jupyter
