docs cleanup

docs/blocks/math.md

@@ -1,37 +1,36 @@
 # Math
 
-[Numeric](/reference/types/number) values: 0, 1, 2, ...
+### [Numeric](/reference/types/number) values: 0, 1, 2, ...
 
-```blocks
+```block
 0;
 1;
 2;
 ```
 
-Arithmetic binary operation (+, -, *, /)
+### Arithmetic binary operation (+, -, *, /)
 
-```blocks
+```block
 0+1;
 0-1;
 1*2;
 3/4;
 ```
 
-Absolute value
+### Absolute value
 
-```blocks
+```block
 Math.abs(-5);
 ```
 
-Minimum/maximum of two values
+### Minimum/maximum of two values
 
-```blocks
+```block
 Math.min(0, 1);
-Math.max(0, 1);
 ```
 
-Random value
+### Random value
 
-```blocks
+```block
 Math.random(5);
 ```

docs/blocks/math/math.md

@@ -1,42 +0,0 @@
-# Math functions
-
-### @parent blocks/language
-
-The math library includes math related functions that you can use with [Numbers](/reference/types/number).
-
-### abs
-
-math `->` abs (x : [Number](/reference/types/number)) *returns* [Number](/reference/types/number)
-
-returns the absolute value of input parameter `x`
-
-![](/static/mb/blocks/math-0.png)
-
-### max
-
-math `->` max (x : [Number](/reference/types/number), y : [Number](/reference/types/number)) *returns* [Number](/reference/types/number)
-
-returns the larger of two input numbers (`x` and `y`)
-
-![](/static/mb/blocks/math-1.png)
-
-### min
-
-math `->` min (x : [Number](/reference/types/number), y : [Number](/reference/types/number)) *returns* [Number](/reference/types/number)
-
-returns the smaller of two input numbers (`x` and `y`)
-
-![](/static/mb/blocks/math-2.png)
-
-### random
-
-math `->` random (limit : [Number](/reference/types/number)) *returns* [Number](/reference/types/number)
-
-returns a random [Number](/reference/types/number) between 0 and the parameter *limit*
-
-![](/static/mb/blocks/math-3.png)
-
-### See also
-
-[Number](/reference/types/number)
-

docs/lessons/blocks-conditions.md

@@ -4,9 +4,11 @@ An introduction to conditions for the Block Editor.
 
 ## Introduction to conditions
 
-In the introduction to code, we made the BBC micro:bit automatically shows the message ‘hello, world!’:
+In the introduction to code, we made the BBC micro:bit automatically shows the message ‘hello world!’:
 
-![](/static/mb/blocks/lessons/blocks-conditions-0.png)
+```blocks
+basic.showString("hello world!")
+```
 
 This statement, or code, will happen as soon as the BBC micro:bit is activated. This means it is unconditional. We can add a condition to make code function in certain ways:
 
@@ -16,11 +18,13 @@ This statement, or code, will happen as soon as the BBC micro:bit is activated.
 
 In programming we use an ‘if’ statement: if this condition is met, do something. Lets add an if statement to the code we had before; the BBC Micro:bit will wait for the user to press a button before showing the image.
 
-### Write the code
-
-Click the **if** category and drag an `if/do` block. Drag the`show string` block we wrote previously into the `do` section of the block. Next click the **input** tab and drag a `button pressed` block, connect it to the open jigsaw of the `if` block. This is our criteria: `if A button is pressed`. We can change which button (button A or B) by clicking the arrow next to ‘A’ and changing the value. This means our BBC micro:bit is waiting for button A (the left button) to be pressed. Finally go to the **basic** tab and drag a `forever` block, and attach all our code inside. We add this block to ensure the BBC micro:bit is always waiting to show us this message, not just once. Your code should look like this:
-
-![](/static/mb/blocks/lessons/blocks-conditions-1.png)
+```blocks
+basic.forever(() => {
+    if (input.buttonIsPressed(Button.A)) {
+        basic.showString("hello world!")
+    }
+})
+```
 
 Again, test the code in the simulator. Try clicking **Button A** to display the "hello, world!" message every time the `button is pressed`.
 
@@ -40,7 +44,15 @@ For example, we could make it so our BBC Micro:bit tells us to press the A butto
 
 We want the message "Press A!" to scroll across the BBC micro:bit, so right-click the `show string` block and select **Duplicate**. Drag this new block into the `else` section and replace the “hello, world!” with "Press A!". Your code should look like this:
 
-![](/static/mb/blocks/lessons/blocks-conditions-2.png)
+```blocks
+basic.forever(() => {
+    if (input.buttonIsPressed(Button.A)) {
+        basic.showString("hello world!")
+    } else {
+        basic.showString("PRESS A")        
+    }
+})
+```
 
 So, to recap: the `forever` block makes sure our code runs forever. The BBC micro:bit checks if the user is pressing the left button, if the user is not then the “Press the button!” message will scroll across the LEDs. If the user is pressing the button then the “hello, world!” message will scroll across the screen. Check this in the simulator or attach the BBC micro:bit to the computer then click **Download** to send the code onto the BBC micro:bit.
 

docs/lessons/challenges.md

@@ -1,88 +0,0 @@
-# blocks - challenges
-
-Extra stuff for the Block Editor - an introduction to GPIO
-
-## Before we get started
-
-This section details challenges for the BBC micro:bit. Ensure you have completed all other sections of the Microsoft Block Editor tutorials before attempting these challenges!
-
-## Quiz Challenge [1]
-
-Using if statements, try to add more statements to create a simple quiz. The user will be told if the question is right or not, and will have two options (button A and button B).
-
-Here is some sample code for a simple quiz:
-
-![](/static/mb/blocks/lessons-0.png)
-
-## Timer Challenge [2]
-
-Create a timer that runs out after a certain amount of time (using the *count* loop). For an extra challenge, let the user input the amount of seconds they want the timer to run for using variables and the buttons as input. The solution is below.
-
-![](/static/mb/blocks/lessons-1.png)
-
-## Graphics Challenges [3]
-
-Using the knowledge you have learnt from the [rendering graphics](/lessons/graphics) section, try creating an algorithm to draw these shapes. Before you write the code try to figure out how the BBC micro:bit will be thinking to plot these points. For example, with our diagonal line – “count up from 0 to 4 by 1, and plot points x=i and y=i”.
-
-* Another diagonal line
-* A square going around the board
-* A filled square
-* A square which unplots itself after
-* A filled square which then unplots itself
-
-The solutions are below.
-
-### Square [3.1]
-
-![](/static/mb/blocks/lessons-2.png)
-
-### Filled square [3.2]
-
-![](/static/mb/blocks/lessons-3.png)
-
-### Vanishing square [3.3]
-
-Use the same code and algorithm for the square solution, only use the ‘unplot’ block to make this LED turn off again. You could also reverse the algorithm.
-
-### Vanishing filled square [3.4]
-
-Use the same code and algorithm for the filled square solution, only use the `unplot` block to make this LED turn off again. You could also reverse the algorithm.
-
-## Animation Challenge [4]
-
-Use your new knowledge of animations and algorithms to program your BBC micro:bit to act human: for example, you could make your BBC micro:bit smile and wink. Remember you can display images with the `show image` and `create image` blocks. Sample code is below.
-
-![](/static/mb/blocks/lessons-4.png)
-
-## Electronic Dice Challenge [5]
-
-Using the code in the Random Numbers tutorial in Section 6, or your own algorithm, create an electronic dice that displays the values appropriate for a dice (so 1 shows a single LED on in the center, two shows two LEDs on at each corner, etc.). You may want to declare image variables to do this, then check what it is equal to using an ‘if’ statement. Sample code is below.
-
-![](/static/mb/blocks/lessons-4.png)
-
-## Calculator Challenge [6]
-
-Using your knowledge of loops, counters and math, create a calculator.
-
-The calculator should:
-
-* Count the amount of times the user presses the left button before pressing the right button (this is the first value, or valueOne)
-* Count the amount of times the user presses the left button before the right button again (this is the second value, or valueTwo)
-* Scroll through operations (+,-, x and divide) until the user presses the right button to make a choice
-* Perform the calculation
-* Show the entire calculation, for example: 5 + 10 = 15
-
-Sample code is below.
-
-![](/static/mb/blocks/lessons-5.png)
-
-## Smart watch Challenge [8]
-
-Create a smart watch using the BBC micro:bit. Create a menu where the user presses one button to cycle through options and another button to choose this option. Add applications to this smart watch:
-
-* Calculators
-* Games
-* Random number generators
-
-And any other applications you can think of.
-

docs/lessons/graphics.md

@@ -6,7 +6,9 @@ An introduction to graphics for the Block Editor.
 
 Ensure you have completed the 'Hello, world!' and Loop tutorials and tested them on a simulator or on BBC micro:bit.
 
-![](/static/mb/blocks/lessons/blocks-conditions-0.png)
+```blocks
+basic.showString("HI!");
+```
 
 The BBC micro:bit has a grid of 25 LEDs, so we can use these to display images.
 
@@ -24,9 +26,16 @@ We can also code our bug to plot a point by giving an x (horizontal) and y (vert
 
 We can also unplot a point (turn the LED off again) using the `unplot` block. So we could create a flashing LED program, using the `pause` block to create a delay.
 
-![](/static/mb/blocks/lessons/graphics-1.png)
+```blocks
+basic.forever(() => {
+    led.plot(2,2)
+    basic.pause(100)
+    led.unplot(2,2)
+    basic.pause(100)
+})
+```
 
-We can also use the `clear screen` block to turn off all LEDs.
+We can also use the `basic.clearScreen` block to turn off all LEDs.
 
 ## Tip
 
@@ -34,26 +43,35 @@ The pause block is in milliseconds, so setting it to 1000 will have a pause of a
 
 ### Devising algorithms for shapes
 
-An algorithm is a set of steps to follow to solve a problem. We can begin to draw shapes on the BBC micro:bit using an algorithm. For example, we could draw a straight line with this code:
+An algorithm is a set of steps to follow to solve a problem. We can begin to draw shapes on the BBC micro:bit using an algorithm. 
+For example, we could draw a straight line with this code:
 
-![](/static/mb/blocks/lessons/graphics-2.png)
+```blocks
+for(let i = 0; i <=4; i++) {
+    led.plot(i, 0);
+    basic.pause(200)
+}
+```
 
 Our algorithm is: increase **i** by 1 **from 0** to **4**, and **plot** the point **x=i**, **y=0**. The pause block allows this line to be animated (drawn frame by frame).
 
-Try devising an algorithm for a diagonal line using the code above and the variable **i**. Your code should look like this; as our variable increases, so does the location that the BBC micro:bit is plotting at:
-
-![](/static/mb/blocks/lessons/graphics-3.png)
-
-We can create more complex algorithms for more complex shapes, too. See the [challenges](/lessons/challenges) section for additional graphical challenges and solutions.
+Try devising an algorithm for a diagonal line using the code above and the variable **i**.
+```sim
+basic.forever(() => {
+    for(let i = 0; i <=4; i++) {
+        led.plot(i, i);
+        basic.pause(200)
+    }
+    basic.clearScreen();
+})
+```
 
 ### Animations
 
-Animations are changes happening at a certain rate. For example, we could add the `delay` block from the **Basic** drawer with our square algorithm – this will slowly draw a square (as an animation).
+Animations are changes happening at a certain rate. For example, we could add the `pause` block from the **Basic** drawer with our square algorithm – this will slowly draw a square (as an animation).
 
 We could create more complex animations, for example we could make our BBC micro:bit display an explosion or fireworks.
 
-See the [challenges](/lessons/challenges) section for some animation tasks.
-
 ### Image variables
 
 We can create image variables so we can easily display an image at a later point. For example:

docs/lessons/loops.md

@@ -1,59 +0,0 @@
-# blocks - loops
-
-An introduction to Loops for the Block Editor.
-
-We may want to handle the user’s input multiple times or remain waiting for their input for a long time. We use loops to make sure that our code runs multiple times. These can be found in the **Loops** drawer.
-
-### Forever loops
-
-In the Variables tutorial we utilised a forever loop to create a counter:
-
-![](/static/mb/blocks/lessons/blocks-conditions-2.png)
-
-This allows our BBC micro:bit to wait for the user to do something forever, for example wait for the user to press the correct button as the example above shows. If you were creating a quiz, you may want to loop forever until the user presses the correct button or answers the question.
-
-### Repeat Loops
-
-Repeat loops allow code to happen a certain amount of times. You may want to create a quiz that only gives the user a few tries to get the correct answer, for example. The number can be changed to facilitate your code.
-
-![](/static/mb/blocks/lessons/loops-0.png)
-
-The code above will scroll the message, “Hello world” three times.
-
-### While & Until loops
-
-The ‘repeat while’ loop allows you to continue looping some code until a condition is met. The empty socket next to the while loop allows you to connect some Logic and construct a statement.
-
-![](/static/mb/blocks/lessons/loops-1.png)
-
-The code above will scroll the message, “Press it!”, while the user hasn’t pressed the button.
-
-* Drag a `set item` block from the **Variables** drawer. Click the **down arrow** and click **New Variable**, and type "pressed". Drag a `0` block from **Maths** to set the variable **pressed** to 0.
-* Drag a `repeat while` block from the **Loops** drawer and attach an `=` block from the **Logic** drawer. Drag `item` from the **Variables** drawer and click the **down arrow**, select ‘pressed’. Drag a `0` block from Maths and connect it to the other side of the equals. This will carry out the code until ‘pressed’ does not equal 0.
-* Add a `show string` block from the **Basic** drawer and change the message to "Press it!"
-* Add an `if` block from the **Logic** drawer, connect a `button pressed` block from the **Input** drawer, and add text from the **Basic** drawer. Change this to A to show we are waiting for button A.
-* Inside the ‘do’ part of the if statement, add a `set` block from the Variables drawer, click the **down arrow** to change it to **pressed** and drag a `1` from the Maths drawer
-* Lastly underneath the while loop, add another `show string` block and fill in the gaps.
-
-Test the code above on actual hardware or on the simulator window.
-
-We can also change the code in subtle ways to have a completely different effect:
-
-![](/static/mb/blocks/lessons/loops-2.png)
-
-This time we have to press the button three times to leave the while loop.
-
-## Tip
-
-You can press the arrow next to a word in a block to change it. For example, you can change Math functions or change a Logic statement.
-
-### Count or for loops
-
-A count loop allows you to loop a certain amount of times and to change a variable as you do so. For example, we can create a simple counting program:
-
-![](/static/mb/blocks/lessons/loops-3.png)
-
-The count loop will repeat a certain amount of times whilst changing a variable. You can click the arrow next to **i** to replace it with any of your own variables. So this program will display numbers 1 to 10.
-
-This loop allows you to repeat code for the amount of times you want to without worrying about manually changing variables. You could use this for a counting program or a timer.
-

olddocs/blocks-vs-js.md

@@ -1,141 +0,0 @@
-# From Block Editor to Touch Develop
-
-#docs
-
-The Block Editor and Touch Develop programming languages provide similar features, but are not identical in their functionality.  This presents a learning opportunity for teachers and students: to understand a few basic concepts and how they are expressed in different programming languages.  The objective is to make students better able to navigate the sea of programming languages they will encounter later.
-
-## Concept 1: Inclusive and exclusive intervals
-
-In mathematics, numeric intervals are a useful shorthand for expressing a sequence of numbers. For example, the notation [0,9] represents the sequence of ten numbers 0,1,2,3,4,5,6,7,8,9. This is known as an "inclusive" interval because the sequence includes the endpoints of the interval, namely 0 and 9.  On the other hand, the interval (0,9) represents the sequence of eight numbers 1,2,3,4,5,6,7,8 and is known as "exclusive".
-
-In the interval notation, the brackets "[" and "]" represent inclusive endpoints and the parentheses "(" and ")" represent exclusive endpoints.  Brackets can be mixed and matched, so [0,9) represents the sequence of nine numbers 0,1,2,3,4,5,6,7,8 while (0,9] represents the sequence of nine numbers 1,2,3,4,5,6,7,8,9. Let's call the former interval "inclusive-exclusive" and the latter interval "exclusive-inclusive".
-
-### Block Editor for loop uses a 0-based inclusive interval
-
-Numeric intervals arise in the context of for loops, both in the Block Editor and Touch Develop. Here's a Block Editor for loop to draw a diagonal line from the top-left corner of the [LED screen](/device/screen) to the bottom-right corner. The loop iteration variable *i* ranges "from 0 to 4":
-
-![](/static/mb/blocks/to-td-0.png)
-
-What interval does "from 0 to 4" represent? The answer is the inclusive interval [0,4], meaning that the loop iteration variable `i` will take on the values 0,1,2,3,4 over the *five* iterations of the loop. Experiments have shown that the *inclusive internal* is most familiar to students with no previous programming experience.
-
-### TouchDevelop for loop uses a 0-based inclusive-exclusive interval
-
-To achieve the same result in Touch Develop, we write the for loop slightly differently because the upper bound of the 0-based loop is *exclusive* rather than inclusive:
-
-```
-for (let i = 0; i < 5; i++) {
-    led.plot(i, i)
-}
-```
-
-If we translated the Block Editor loop directly into Touch Develop, we would have:
-
-```
-for (let i1 = 0; i1 < 4; i1++) {
-    led.plot(i1, i1)
-}
-```
-
-which would result in the loop iteration variable taking on values in the interval [0,4), namely 0,1,2,3.
-
-### ~hint 
-
-The use of an exclusive upper-bound in for loops is standard practice in most programming languages. The basic reason for this is that with a 0-based inclusive lower bound, an exclusive upper bound U conveniently happens to be the length of the sequence represented by [0,U). This, of course, begs the question of why we count by starting with zero (0) in programming whereas we learn to count with one (1) in math.
-
-### ~
-
-## Concept 2: variable scope
-
-A variable's *scope* is defined by two other concepts: its *lifetime* and *visibility*.  Imagine program execution like a timeline with each point in the timeline being a step in the program's execution.
-
-* A variable's *lifetime* can be thought of as an interval [birth, death) in the program execution during which the variable exists and has a value. Within that interval of the program execution, we say the variable is *alive*.
-* A variable is visible if its value can be read/written at a point in program execution. Visibility often is based on program structure and where the current point of program execution is. Imagine program structure like a house with only doors and no windows: if you are outside the house, you cannot see the objects (variables) inside the house - they are not visible to you even though they may exist; however, if you enter the house through the door, you can see the variables inside the house. The house itself may be divided into rooms, each of which defines another space in which certain variables are visible and others are not visible.
-
-A variable is "in scope" at a program point if it is both alive and visible at that point. A variable is "not in scope" if it is not alive or if it is not visible.
-
-### The Block Editor has variables with only global scope
-
-In the Block Editor, all variables are *global* variables, which means that all variables are alive and visible during the entire program execution. Consider the following Block Editor program:
-
-![](/static/mb/blocks/to-td-1.png)
-
-This program will draw a diagonal line, wait for one second and then show the value of global variable `i`. What number will be shown on the LED screen? After the fifth iteration of the for loop, the value of variable `i` is 4. At the end of this iteration, the variable `i` is incremented and takes on the value 5. Since 5 is greater than the upper (inclusive) endpoint of 4, the loop terminates with the value of `i` at 5.
-
-### Problems with global variables: unintended interference
-
-The Block Editor program belows shows a problem with having only variables with global scope. The intent of the program below is fairly clear: if the user presses button A, slowly draw a diagonal line from top-left to lower-right; if the user presses button B, slowly draw a diagonal line from top-right to lower-left. Pressing both buttons should lead to an X being displayed on the screen.
-
-![](/static/mb/blocks/to-td-2.png)
-
-The problem with the above program is that we have two loops using the same global variable *i* as the loop iteration variable.  If the user first presses button A and then quickly presses button B, the loops execute concurrently, both reading and writing global variable *i* - this can cause unexpected results (in particular, you won't necessarily end up with an X displayed on the screen).  You can see this more clearly by pressing the convert button in the Block Editor and examining the Touch Develop code that implements the Block Editor semantics:
-
-![](/static/mb/blocks/to-td-3.png)
-
-### JavaScript has variables with both local and global scope
-
-In Touch Develop, in contrast to the Block Editor, the for-loop iteration variable has scope that is local to the loop:
-
-```
-for (let i2 = 0; i2 < 5; i2++) {
-    led.plot(i2, i2)
-}
-```
-
-This means that:
-
-1.  the loop iteration variable *i* comes into existence just before the loop begins and goes out of existence just after the loop terminates.
-
-2. the variable `i` only is visible from the code that appears textually between the `do` and `end` keywords of the for loop (this is known as lexical scoping).
-
-The value of the loop iteration variable is completely determined by the semantics of the for loop. As such, Touch Develop doesn't allow the programmer to overwrite the value of a loop iteration variable, as shown below:
-
-```
-for (let i3 = 0; i3 < 5; i3++) {
-    led.plot(i3, i3)
-    i3 = 42
-}
-```
-
-### Why is local scope useful?
-
-Local scope allows you to use the same variable name in different parts of a program without concern about interference (as with variables with global scope). Here's the Touch Develop program that implements the "X" program without interference:
-
-```
-input.onButtonPressed(Button.A, () => {
-    for (let i4 = 0; i4 < 5; i4++) {
-        led.plot(i4, i4)
-        basic.pause(1000)
-    }
-})
-input.onButtonPressed(Button.B, () => {
-    for (let i5 = 0; i5 < 5; i5++) {
-        led.plot(4 - i5, i5)
-        basic.pause(1000)
-    }
-})
-```
-
-Even though the same variable name (i) appears in both loops, these are different variables, each with their own lifetime and visibility (as defined by the for-loop).
-
-## Concept 3: static types
-
-A variable has a *static type* if it holds the same kind of value (integer, string, Boolean) everywhere that it is in scope.  If a variable can hold values of different types at different program locations, then it does not have a static type.
-
-### Block Editor blocks not plugged to an event will run
-
-Blocks not plugged to an event will run. Blocks are running even if they are not inside of an `event`. As shown below, ``show string`` *Hello* will show a string on the LED screen one character at a time (scrolling from left to right).
-
-![](/static/mb/blocks/to-td-4.png)
-
-### Google's Blockly variables do not have static types
-
-In Blockly, a variable can hold different types of values at different program locations. As shown below, the global variable *Count* can be first set to a number and later to a string:
-
-![](/static/mb/blocks/to-td-5.png)
-
-### Block Editor and Touch Develop variables have static types
-
-In the Block Editor (based on Blockly) and Touch Develop, each variable has a static type. This means that some programs don't make sense, such as:
-
-![](/static/mb/blocks/to-td-6.png)
-