docs and examples

docs/introduction.md

@@ -34,13 +34,15 @@ The command prompt should disappear and you will see a blank screen. It will loo
 
 Hit ++ctrl+c++ to exit and return to the command prompt.
 
+### The code
+
 The first step in all Textual applications is to import the `App` class from `textual.app` and extend it:
 
 ```python hl_lines="1 2 3 4 5" title="intro01.py"
 --8<-- "docs/examples/introduction/intro01.py"
 ```
 
-There will be a single App class in any Textual application. The App class is responsible for loading data, setting up the screen, managing events etc. In a real app most of the core logic of your application will be contained within methods on the this class.
+This App class is responsible for loading data, setting up the screen, managing events etc. In a real app most of the core logic of your application will be contained within methods on the this class.
 
 The last two lines create an instance of the application and calls `run()`:
 
@@ -52,13 +54,15 @@ The `run` method will put your terminal in to "application mode" which disables
 
 ## Handling Events
 
-In the previously example our app did next to nothing. Most applications will contain event handler methods, which are called in response to user actions such as key presses and mouse movements in addition to other changes your app needs to know about such as terminal resize, scrolling, timers, etc.
+Most real-world applications will want to interact with the user in some way. To do this we can make use of _event handler_ methods, which are called in response to things the user does such as pressing a key(s), moving the mouse, resizing the terminal, etc.
+
+Each event type is represented by an event object, which is an instance of a class containing information you may need to respond the the event. For instance the `Key` event contains the key the user pressed and a `Mouse` event will contain the coordinates of the mouse cursor.
 
 !!! note
 
     Although `intro01.py` did not explicitly define any event handlers, Textual still had to respond to events to catch ++ctrl+c++, otherwise you wouldn't be able to exit the app.
 
-In our next example, we are going to handle two events; `Mount` and `Key`. The `Mount` event is sent when the app is first run, and a `Key` event is sent when the user presses a key on the keyboard. Try running `intro02.py` in the `docs/examples/introduction`:
+The next example demonstrates handling events. Try running `intro02.py` in the `docs/examples/introduction`:
 
 ```python title="intro02.py"
 --8<-- "docs/examples/introduction/intro02.py"
@@ -78,17 +82,17 @@ If you hit any of the number keys ++0++-++9++, the background will change color
 
 There are two event handlers in this app. Event handlers start with the text `on_` followed by the name of the event in lower case. Hence `on_mount` is called for the `Mount` event, and `on_key` is called for the `Key` event.
 
-The first event handler to run is `on_mount`:
+The first event handler to run is `on_mount`. The `Mount` is sent to your application immediately after entering application mode.
 
 ```python hl_lines="19 20" title="intro02.py"
 --8<-- "docs/examples/introduction/intro02.py"
 ```
 
-This `on_mount` method sets the `background` attribute of `self.styles` to `"darkblue"` which updates the background color. There are a lot of other properties on the Styles object, which define how your app looks. We will explore what you can do with this object later.
+This `on_mount` method sets the `background` attribute of `self.styles` to `"darkblue"` which makes the background blue when the application starts. There are a lot of other properties on the Styles object, which define how your app looks. We will explore what you can do with this object later.
 
 !!! note
 
-    You may have noticed there was no function call to repaint the screen in this examples. Textual will detect when a refresh is required, and do it automatically.
+    You may have noticed there is no function call to repaint the screen in this example. Textual is generally quite smart in detecting when a refresh is required, and updating the screen automatically.
 
 The second event handler will receive `Key` events whenever you press a key on the keyboard:
 
@@ -96,15 +100,15 @@ The second event handler will receive `Key` events whenever you press a key on t
 --8<-- "docs/examples/introduction/intro02.py"
 ```
 
-This method has an `event` positional argument which contains information regarding the key that was pressed. The body of the method sets the background to a corresponding color int the `COLORS` list when you press one of the digit keys. It also calls `bell()` which is a method on App that plays your terminal's bell.
+This method has an `event` positional argument which will receive the event object; in this case the `Key` event. The body of the method sets the background to a corresponding color in the `COLORS` list when you press one of the digit keys. It also calls `bell()` which is a method on App that plays your terminal's bell.
 
 !!! note
 
-    Every event has a corresponding `Event` object, but Textual knows to only call the event handler with the event object if you have it in the argument list. It does this by inspecting the handler method prior to calling it.
+    Every event has a corresponding `Event` object, but Textual knows to only call the event handler with the event object if you have it in the argument list. It does this by inspecting the handler method prior to calling it. So if you don't need the event object, you may leave it out.
 
 ## Widgets
 
-Most Textual applications will also make use of one or more `Widget` classes. A Widget is a self contained component responsible for defining how a given part of the screen should look. Widgets respond to events in much the same way as the App does.
+Most Textual applications will make use of one or more `Widget` classes. A Widget is a self contained component responsible for defining how a given part of the screen should look. Widgets respond to events in much the same way as the App does.
 
 Let's look at an app with a simple Widget to show the current time and date. Here is the code for `"clock01.py"` which is in the same directory as the previous examples:
 
@@ -124,7 +128,7 @@ This script imports App as before, but also the `Widget` class from `textual.wid
 --8<-- "docs/examples/introduction/clock01.py"
 ```
 
-Widgets support many of the same events as the Application itself, and can be thought of as mini-applications in their own right. The Clock widget also responds to a Mount event which is the first event received when a widget is _mounted_ (added to the App). The code in `Clock.on_mount` sets `styles.content_align` to tuple of `("center", "middle")` which tells Textual to display the Widget's content aligned to the horizontal center, and in the middle vertically. If you resize the terminal, you should find the time remains in the center.
+Widgets support many of the same events as the Application itself, and can be thought of as mini-applications in their own right. The Clock widget responds to a Mount event which is the first event received when a widget is _mounted_ (added to the App). The code in `Clock.on_mount` sets `styles.content_align` to tuple of `("center", "middle")` which tells Textual to display the Widget's content aligned to the horizontal center, and in the middle vertically. If you resize the terminal, you should find the time remains in the center.
 
 The second line in `on_mount` calls `self.set_interval` which tells Textual to invoke the `self.refresh` function once a second to refresh the Clock widget.