From 21361708ec260f5fbd27d1a40d4affd01d3c12b2 Mon Sep 17 00:00:00 2001 From: Ron Hale-Evans Date: Fri, 20 May 2016 13:09:18 -0700 Subject: [PATCH 1/6] Rest of Basic in simple English. Reconsider some code samples? --- docs/reference/basic/forever.md | 18 +++++++++++++----- docs/reference/basic/pause.md | 9 ++++++--- 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/docs/reference/basic/forever.md b/docs/reference/basic/forever.md index 9b4a0a24..c666badc 100644 --- a/docs/reference/basic/forever.md +++ b/docs/reference/basic/forever.md @@ -1,6 +1,7 @@ # Forever -Repeat code [in the background](/reference/control/in-background) forever. +Keep running part of a program +[in the background](/reference/control/in-background). ```sig basic.forever(() => { @@ -9,7 +10,9 @@ basic.forever(() => { ### Example: compass -The following example constantly checks the [compass heading](/reference/input/compass-heading) and updates the screen with the direction. +The following example constantly checks the +[compass heading](/reference/input/compass-heading) +and updates the screen with the direction. ```blocks basic.forever(() => { @@ -30,7 +33,9 @@ basic.forever(() => { ### Example: counter -The following example continually shows the current value of a global variable: +The following example keeps showing the [number](/reference/types/number) stored in a global variable. +When you press button `A`, the number gets bigger. +You can use a program like this to count things with your BBC micro:bit. ```blocks let num = 0 @@ -42,9 +47,12 @@ input.onButtonPressed(Button.A, () => { }) ``` -### Contention for the LED display +### Competing for the LED screen -If you have multiple processes that each show something on the LED screen, you may get unexpected results. Try, for example: +If different parts of a program are each trying +to show something on the LED screen at the same time, +you may get unexpected results. +Try this on your micro:bit: ```blocks basic.forever(() => { diff --git a/docs/reference/basic/pause.md b/docs/reference/basic/pause.md index 776be176..a6bb0d10 100644 --- a/docs/reference/basic/pause.md +++ b/docs/reference/basic/pause.md @@ -1,6 +1,7 @@ # Pause -Pause program execution for the specified number of milliseconds. This function is helpful when you need to slow down your program's execution. +Pause the program for the number of milliseconds you say. +You can use this function to slow your program down. ```sig basic.pause(400) @@ -8,11 +9,13 @@ basic.pause(400) ### Parameters -* ``ms`` - the number of milliseconds that you want to pause (100 = 1/10 second, 1000 milliseconds = 1 second) +* ``ms`` is the number of milliseconds that you want to pause (100 milliseconds = 1/10 second, and 1000 milliseconds = 1 second). ### Example: diagonal line -The following example code turns on LED `0, 0` thru `4, 4`, pausing 500 milliseconds after each LED. Without `pause`, the code would run so fast that you wouldn't see each individual LED turning on. +This example draws a diagonal line by turning on LED `0, 0` (top left) through LED `4, 4` (bottom right). +The program pauses 500 milliseconds after turning on each LED. +Without `pause`, the program would run so fast that you would not have time to see each LED turning on. ```blocks for (let i = 0; i < 5; i++) { From 4abdb28a59fcfc7cd87c41807331b48d1f2d689f Mon Sep 17 00:00:00 2001 From: Ron Hale-Evans Date: Fri, 20 May 2016 13:24:27 -0700 Subject: [PATCH 2/6] More simple English docs. --- docs/reference/basic/clear-screen.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/basic/clear-screen.md b/docs/reference/basic/clear-screen.md index 0d03227c..eed059e8 100644 --- a/docs/reference/basic/clear-screen.md +++ b/docs/reference/basic/clear-screen.md @@ -8,7 +8,7 @@ basic.clearScreen() ### Example: vanishing heart -The following code displays a heart on the screen and then turns off all the LED lights using `clear screen`: +The following code shows a heart on the screen and then turns off all the LED lights using `clear screen`: ```blocks basic.showLeds(` From 919c8fdfcab85b1c668305102b17b699615a11c4 Mon Sep 17 00:00:00 2001 From: Ron Hale-Evans Date: Fri, 20 May 2016 15:33:15 -0700 Subject: [PATCH 3/6] Rewrite in simple English, debug the examples. --- docs/reference/input/on-button-pressed.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/reference/input/on-button-pressed.md b/docs/reference/input/on-button-pressed.md index 8d262566..df0c22bc 100644 --- a/docs/reference/input/on-button-pressed.md +++ b/docs/reference/input/on-button-pressed.md @@ -1,6 +1,9 @@ # On Button Pressed -Register an [event handler](/reference/event-handler) that will execute whenever an input button (A, B, or A and B together) is pressed during program execution. When [running code](/device/simulator) with this function in a web browser, click an on-screen input button - labelled A or B. +Start an [event handler](/reference/event-handler) (part of the program that will run when something happens, like when a button is pressed). +This handler works when button `A` or `B` is pressed, or `A` and `B` together. +When you are using this function in a web browser, click the buttons on the screen instead of the ones +on the BBC micro:bit. ```sig input.onButtonPressed(Button.A, () => {}) @@ -8,7 +11,8 @@ input.onButtonPressed(Button.A, () => {}) ### Example: count button clicks -This example counts how many times the left or right input button is pressed. Each time a button is pressed, the global count variable is increased by 1 and displayed on the screen. +This example counts how many times you press the `A` button. +Each time you press the button, the [LED screen](/device/screen) shows the `count` variable getting bigger. ```blocks let count = 0 @@ -19,22 +23,29 @@ input.onButtonPressed(Button.A, () => { }) ``` -### Example: roll a dice +### Example: roll dice -This example generates a random number when you press the B input button, and then displays a random die image: +This example generates a number from 1 to 6 when you press the `B` button. Then it shows the number. ```blocks input.onButtonPressed(Button.B, () => { - let dice = Math.random(6) + let dice = Math.random(6) + 1 basic.showNumber(dice) }) ``` +### ~hint + +This program adds a `1` to `random(6)` so the numbers on the dice will come out right. +Otherwise, sometimes they would show a `0`. + +### ~ + ### Lessons [smiley](/lessons/smiley), [answering machine](/lessons/answering-machine), [screen wipe](/lessons/screen-wipe), [rotation animation](/lessons/rotation-animation) ### See also -[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever) +[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever), [random](/reference/math/math) From 86b35ae88d21ae6efea30396886ce480e71f798f Mon Sep 17 00:00:00 2001 From: Ron Hale-Evans Date: Fri, 20 May 2016 15:36:37 -0700 Subject: [PATCH 4/6] Absolutely necessary tiny tweak. --- docs/reference/input/on-button-pressed.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/input/on-button-pressed.md b/docs/reference/input/on-button-pressed.md index df0c22bc..6fbf7583 100644 --- a/docs/reference/input/on-button-pressed.md +++ b/docs/reference/input/on-button-pressed.md @@ -25,7 +25,7 @@ input.onButtonPressed(Button.A, () => { ### Example: roll dice -This example generates a number from 1 to 6 when you press the `B` button. Then it shows the number. +This example shows a number from 1 to 6 when you press the `B` button. ```blocks input.onButtonPressed(Button.B, () => { From a67164d5e66cdb974ef186207923f9a88899f149 Mon Sep 17 00:00:00 2001 From: Ron Hale-Evans Date: Fri, 20 May 2016 16:05:45 -0700 Subject: [PATCH 5/6] Making another topic easier to understand. --- docs/reference/input/button-is-pressed.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/reference/input/button-is-pressed.md b/docs/reference/input/button-is-pressed.md index 6bb974cf..0f8e073e 100644 --- a/docs/reference/input/button-is-pressed.md +++ b/docs/reference/input/button-is-pressed.md @@ -1,6 +1,6 @@ # Button Is Pressed -Get the state of an input button. The micro:bit has two input buttons: A and B. +Check whether a button is pressed right now. The micro:bit has two buttons: button `A` and button `B`. ```sig input.buttonIsPressed(Button.A); @@ -8,24 +8,26 @@ input.buttonIsPressed(Button.A); ### Parameters -* name - [String](/reference/types/string); input button "A", "B", or "A+B" (both input buttons) +* ``name`` is a [String](/reference/types/string). You should store `A` in it to check the left button, `B` to check the right button, or `A+B` to check both at the same time. ### Returns -* [Boolean](/reference/types/boolean) - `true` if pressed, `false` if not pressed +* [Boolean](/reference/types/boolean) that is `true` if the button you are checking is pressed, `false` if it is not pressed. ### Example -The following code uses an [if](/reference/logic/if) statement to run code, depending on whether or not the A button is pressed: +This program uses an [if](/reference/logic/if) to run +one part of the program if the `A` button is pressed, and +another part if it is not pressed. ```blocks basic.forever(() => { let pressed = input.buttonIsPressed(Button.A) if (pressed) { - // this code runs if the A button is pressed + // this part runs if the A button is pressed basic.showNumber(1, 150) } else { - // this code runs if the A button is *not* pressed + // this part runs if the A button is *not* pressed basic.showNumber(0, 150) } }) From 28d28eb67f28108e9190e61bcd36487ecdc12a3a Mon Sep 17 00:00:00 2001 From: Ron Hale-Evans Date: Fri, 20 May 2016 18:33:31 -0700 Subject: [PATCH 6/6] Rewrite text, code sample. --- docs/reference/loops/for.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/reference/loops/for.md b/docs/reference/loops/for.md index b8ebe9cd..0ecc0d0c 100644 --- a/docs/reference/loops/for.md +++ b/docs/reference/loops/for.md @@ -2,17 +2,15 @@ ### @parent blocks/language -Repeat code a fixed number of times. +Run part of the program the number of times you say. + +### Example: Count to 4 + +This program will show the numbers 0, 1, 2, 3, and 4 one after another on the LED screen. ```blocks for(let i = 0; i < 5; ++i) { -} -``` - -The Block Editor *for* loop is different than the Touch Develop *for* loop in an important way. The above for loop will iterate *five* times, with the loop variable *i* taking on values 0, 1, 2, 3, and 4. The Touch Develop for loop shown below will iterate four times: - -``` -for (let k = 0; k < 4; k++) { +basic.showNumber(i) } ``` @@ -22,5 +20,5 @@ for (let k = 0; k < 4; k++) { ### See also -[while](/reference/loops/while), [if](/reference/logic/if) +[while](/reference/loops/while), [if](/reference/logic/if), [show number](/reference/basic/show-number)