docs: Getting started tidyups

docs/getting_started.rst

@@ -27,11 +27,11 @@ and possibly your team with:
 
 * While high-level abstractions are provided, you must understand how Mitogen
   works before depending on it. Mitogen interacts with many aspects of the
-  operating system, network, SSH, sudo, sockets, TTYs, Python runtime, and
+  operating system, network, SSH, sudo, sockets, TTYs, shell, Python runtime,
-  timing and ordering uncertainty introduced through interaction with the
+  and timing and ordering uncertainty introduced through interaction with the
   network and OS scheduling.
 
-  Knowledge of this domain is typically gained through painful years of ugly
+  Knowledge of this domain is typically gained through painful years of failed
   attempts hacking system-level programs, and learning through continual
   suffering how to debug the messes left behind. If you feel you lack resources
   to diagnose problems independently, Mitogen is not appropriate, prefer a
@@ -56,22 +56,25 @@ them to a callback from the broker thread (registered by
 :py:meth:`add_handler() <mitogen.core.Router.add_handler>`), or forwarding them
 to a :py:class:`Stream <mitogen.core.Stream>`. See :ref:`routing` for an
 in-depth description. :py:class:`Router` also doubles as the entry point to
-Mitogen's public API.
+Mitogen's public API:
 
 .. code-block:: python
 
-    broker = mitogen.master.Broker()
+    >>> import mitogen.master
-    router = mitogen.master.Router(broker)
 
-    try:
+    >>> broker = mitogen.master.Broker()
-        # Your code here.
+    >>> router = mitogen.master.Router(broker)
-    finally:
+
-        broker.shutdown()
+    >>> try:
+    ...     # Your code here.
+    ...     pass
+    ... finally:
+    ...     broker.shutdown()
 
-As your program will not exit if threads are still running when the main thread
+As Python will not stop if threads still exist after the main thread exits,
-exits, it is crucial :py:meth:`Broker.shutdown` is called reliably at exit.
+:py:meth:`Broker.shutdown` must be called reliably at exit. Helpers are
-Helpers are provided by :py:mod:`mitogen.utils` to ensure :py:class:`Broker` is
+provided by :py:mod:`mitogen.utils` to ensure :py:class:`Broker` is reliably
-reliably destroyed:
+destroyed:
 
 .. code-block:: python
 
@@ -82,7 +85,7 @@ reliably destroyed:
 
 If your program cannot live beneath :py:func:`mitogen.utils.run_with_router` on
 the stack, you must must arrange for :py:meth:`Broker.shutdown` to be called
-anywhere exit of the main thread may be triggered.
+anywhere the main thread may exit.
 
 
 Creating A Context