Update device/reactive page (#1626)

docs/device/reactive.md

@@ -10,35 +10,35 @@ There are different types of computing systems, to address different kinds of pr
 
 ## ~
 
-The micro:bit is a *reactive system* – it reacts continuously to external events, such as a person pressing the A button of the micro:bit or shaking the device. The reaction to an event may be to perform a computation, update variables, and change the display.  After the device reacts to an event, it is ready to react to the next one. If this sounds like a computer game, that’s because most computer games are reactive systems too!
+The micro:bit is a *reactive system* – it reacts continuously to external events, such as a person pressing the **A** button of the micro:bit or shaking the device. The reaction to an event may be to perform a computation, update variables, and change the display.  After the device reacts to an event, it is ready to react to the next one. If this sounds like a computer game, that’s because most computer games are reactive systems too!
 
 ## Responsiveness
 
-We want reactive systems to be responsive, which means to react in a timely manner to events. For example, when you play a computer game, it’s frustrating if you press a button to make a character jump, but it doesn’t immediately jump.  A delay in reacting, or lack of responsiveness , can be the difference between life and death, both in the real and virtual worlds.
+We want reactive systems to be responsive, which means to react in a timely manner to events. For example, when you play a computer game, it’s frustrating if you press a button to make a character jump, but it doesn’t immediately jump.  A delay in reacting, or lack of responsiveness, can be the difference between life and death, both in the real and virtual worlds.
 
-Let’s consider a simple example: you want to program your micro:bit to accurately count the number of times the A button has been pressed and continuously display the current count on the 5x5 [LED screen](/device/screen).   Because the LED screen is small, we can only display one digit of a number at a time on it. The [show number](/reference/basic/show-number) function will scroll the digits of a number across the screen so you can read it.
+Let’s consider a simple example: you want to program your micro:bit to accurately count the number of times the **A** button has been pressed and continuously display the current count on the 5x5 [LED screen](/device/screen).   Because the LED screen is small, we can only display one digit of a number at a time on it. The [show number](/reference/basic/show-number) function will scroll the digits of a number across the screen so you can read it.
 
-Let’s say that the current count is 42 and the number 42 is scrolling across the LED screen. This means there is some code executing to perform the scroll.  So, what should happen if you press the A button during the scroll?  It would be a bad idea to ignore the button press, so some code should record the occurrence of the button press. But we just said there already is code running in order to scroll the number 42!  If we wait until the code scrolling the 42 has finished to look for a button press, we will miss the button press.  We want to avoid this sort of unresponsiveness.
+Let’s say that the current count is 42 and the number 42 is scrolling across the LED screen. This means there is some code executing to perform the scroll.  So, what should happen if you press the **A** button during the scroll?  It would be a bad idea to ignore the button press, so some code should record the occurrence of the button press. But we just said there already is code running in order to scroll the number 42!  If we wait until the code scrolling the 42 has finished to look for a button press, we will miss the button press.  We want to avoid this sort of unresponsiveness.
 
 ## Concurrency
 
-To be responsive, a reactive system needs to be able to do several things at the same time (concurrently), just like you can.  But the micro:bit only has one CPU for executing your program, which means it can only execute one program instruction at a time. On the other hand, it can execute millions of instructions in a single second.  This points the way to a solution.
+To be responsive, a reactive system needs to be able to do several things at the same time (concurrently), just like you can.  But the micro:bit only has one CPU for executing your program, which means it can only execute one program instruction at a time. It can, however, execute millions of instructions in a single second. This points the way to a solution.
 
 Think about how a motion picture projector works - it projects only 24 frames per second, yet this is good enough to provide the illusion of fluid motion on the screen. The micro:bit can execute millions of instructions per second, so it seems quite possible for the device to both to smoothly scroll the number 42 across the LED screen while looking for button presses and counting them.
 
 Let’s think about three sequences of instructions:
 
-* Sequence S1 contains the instructions (let’s say several hundred thousand or so) that scroll the number 42 across the LED screen;
-* Sequence S2 contains a few instructions to check if button A is pressed;
-* Sequence S3 contains a few instructions to increment a counter.
+* Sequence **S1**: contains the instructions (let’s say several hundred thousand or so) that scroll the number 42 across the LED screen.
+* Sequence **S2**: contains a few instructions to check if button **A** is pressed.
+* Sequence **S3**: contains a few instructions to increment a counter.
 
-In order to be responsive, we would like to *interrupt* the execution of sequence S1 *periodically* to execute the sequence S2, which will check if button A is pressed, which looks like:
+In order to be responsive, we would like to *interrupt* the execution of sequence **S1** *periodically* to execute the sequence **S2**, which will check if button **A** is pressed, which looks like:
 
-TODO Diagram
+![Execution sequence diagram: S1 and S2](/static/mb/device/reactive-0.png)
 
-The result is that it takes sequence S1 a little longer to complete, due to the interruptions to execute sequence S2, but we are checking often enough to detect a press of button A .  When S2 detects a press of button A, then the sequence S3 can be executed before S1 resumes:
+The result is that it takes sequence **S1** a little longer to complete, due to the interruptions to execute sequence **S2**, but we are checking often enough to detect a press of button **A** .  When **S2** detects a press of button **A**, then the sequence **S3** can be executed before **S1** resumes:
 
-TODO Diagram
+![Execution sequence diagram: S1 and S2 with interrupt and one S3 slice](/static/mb/device/reactive-1.png)
 
 As we’ll soon see, there are other choices for how the sequences can be ordered to achieve the desired result.
 
@@ -66,7 +66,7 @@ The first statement initializes the global variable `count` to zero.
 let count = 0
 ```
 
-The second statement informs the scheduler that on each and every event of the A button being pressed, a subprogram (called the event handler) should be queued for execution. The event handler is demarcated by the do/end keywords; it increments the global variable `count` by one.  
+The second statement informs the scheduler that on each and every event of the **A** button being pressed, a subprogram (called the event handler) should be queued for execution. The event handler is contained within the braces `{...}`; it increments the global variable `count` by one.  
 
 ```blocks
 let count = 0
@@ -76,7 +76,7 @@ input.onButtonPressed(Button.A, () => {
 })
 ```
 
-The third statement queues a `forever` loop for later execution by the scheduler; the body of this loop (between the do/end keywords) displays the current value of global variable `count` on the LED screen.
+The third statement queues a `forever` loop for later execution by the scheduler; the body of this loop (also inside the braces `{...}`) displays the current value of global variable `count` on the LED screen.
 
 ```blocks
 let count = 0
@@ -128,19 +128,24 @@ The property of such round-robin scheduling is that under the assumption that ev
 
 ## Putting it all together
 
-Let’s go back to the `count button presses` program and revisit its execution based on what we have learned about the micro:bit scheduler. As detailed before, the function executes three steps to: (1) set up the event handler for each press of button A; (2) queue the forever loop to the run queue; (3) initialize the global variable `count` to zero.
+Let’s go back to the `count button presses` program and revisit its execution based on what we have learned about the micro:bit scheduler. As detailed before, the function executes three steps to:
+
+1. Set up the event handler for each press of button **A**
+2. Queue the forever loop to the run queue
+3. Initialize the global variable `count` to zero
 
 The function then ends execution and control passes back to the scheduler.  Let’s assume the user has not pressed any buttons . The scheduler finds the `forever` loop in the run queue and passes control to it. The loop first calls `basic.showNumber(0)`.  In the diagram below, we use “Show 0” to refer to the execution of this function:
 
-![](/static/mb/device/reactive-3.png)
+![Execution sequence diagram: display loop with increment and interrupt](/static/mb/device/reactive-3.png)
 
-While "Show 0" (the blue sequence) is running, periodic interrupts by the scheduler (every 6 milliseconds) poll for button presses and queue an event handler for each press of button A. Let’s say that one button press takes place during this time, as shown above. This will cause an event handler (labelled “inc”) to be queued for later execution by the scheduler. Once the "Show 0" has completed, the loop then calls `basic.pause(20)` to put the forever loop to sleep for 20 milliseconds and give the scheduler an opportunity to run any newly queued event handler. Control passes to the “inc” event handler which will increment the global variable `count` from 0 to 1 and then complete, returning control to the scheduler. At some point, the `forever` loop moves from the sleep queue to the run queue; the `forever` loop then will resume and call `basic.showNumber(1)`.
+
+While "Show 0" (the blue sequence) is running, periodic interrupts by the scheduler (every 6 milliseconds) poll for button presses and queue an event handler for each press of button **A**. Let’s say that one button press takes place during this time, as shown above. This will cause an event handler (labelled “inc”) to be queued for later execution by the scheduler. Once the "Show 0" has completed, the loop then calls `basic.pause(20)` to put the forever loop to sleep for 20 milliseconds and give the scheduler an opportunity to run any newly queued event handler. Control passes to the “inc” event handler which will increment the global variable `count` from 0 to 1 and then complete, returning control to the scheduler. At some point, the `forever` loop moves from the sleep queue to the run queue; the `forever` loop then will resume and call `basic.showNumber(1)`.
 
 ## Final thoughts
 
 Through this example, we have seen that the micro:bit scheduler enables you to create a program that is composed of concurrent subprograms. In essence, the programmer needs to only think about the concurrent subprograms cooperatively passing control back to the scheduler, making sure no subprogram hogs control (or “dribbles the ball without passing”) for too long. While a subprogram runs, the scheduler polls the buttons and other IO peripherals at a high frequency in order to fire off events and queue event handlers for later execution, but this is invisible to the programmer.
 
-As a result, you can easily add a new capability to the micro:bit by just adding a new subprogram. For example, if you want to add a reset feature to the counter program, all you need to do is add a new event handler for a press of button B that sets the global variable "count" to zero, as shown below:
+As a result, you can easily add a new capability to the micro:bit by just adding a new subprogram. For example, if you want to add a reset feature to the counter program, all you need to do is add a new event handler for a press of button **B** that sets the global variable "count" to zero, as shown below:
 
 ```typescript
 function countButtonPressesWithReset() {