From befbdd32cc09e78e1c4bccc933773eb3bbb07471 Mon Sep 17 00:00:00 2001 From: Ron Hale-Evans Date: Thu, 19 May 2016 16:50:02 -0700 Subject: [PATCH] Four rewrites of basic.* API pages in simple English. --- docs/reference/basic/show-animation.md | 24 ++++++++++++++++-------- docs/reference/basic/show-leds.md | 11 ++++++----- docs/reference/basic/show-number.md | 10 +++++----- docs/reference/basic/show-string.md | 14 +++++++------- 4 files changed, 34 insertions(+), 25 deletions(-) diff --git a/docs/reference/basic/show-animation.md b/docs/reference/basic/show-animation.md index 2b7bef83..3a099c7d 100644 --- a/docs/reference/basic/show-animation.md +++ b/docs/reference/basic/show-animation.md @@ -1,6 +1,6 @@ # Show Animation -Show a series of image frames on the [LED screen](/device/screen), pausing the specified time after each frame. +Show a group of image frames (pictures) one after another on the [LED screen](/device/screen). It pauses the amount of time you tell it after each frame. ```sig basic.showAnimation(` @@ -14,10 +14,14 @@ basic.showAnimation(` ### Parameters -* `leds` - [String](/reference/types/string); a series of LED on/off states -* `interval` - [Number](/reference/types/number); the number of milliseconds to pause after each image frame +* `leds` is a [String](/reference/types/string) that shows which LEDs are on and off, in groups one after another. +* `interval` is an optional [Number](/reference/types/number). It means the number of milliseconds to pause after each image frame. -### Show a series of image frames +### Example: Animating a group of image frames + +In this animation, each row is 15 spaces wide because +there are three frames in the animation, and each frame is +five spaces wide, just like the screen on the BBC micro:bit. ``` basic.showAnimation(` @@ -31,13 +35,17 @@ basic.showAnimation(` ### ~hint -If the series of images appear too fast, increase the value of the *interval* parameter. +If the animation is too fast, make `interval` bigger. ### ~ -### Example: animating frames +### Example: animating frames with a pause -The following example creates an image with six frames and then shows each frame o the screen, pausing 500 milliseconds after each frame: +This example shows six frames on the screen, pausing 500 milliseconds after each frame. + +In this animation, each row is 30 spaces wide because +there are six frames in the animation, and each frame is +five spaces wide, just like the screen. ``` basic.showAnimation(` @@ -51,7 +59,7 @@ basic.showAnimation(` ### ~hint -Use [forever](/reference/basic/forever) to continually repeat an animation +Use [forever](/reference/basic/forever) to show an animation over and over. ### ~ diff --git a/docs/reference/basic/show-leds.md b/docs/reference/basic/show-leds.md index 45a6d057..e5419057 100644 --- a/docs/reference/basic/show-leds.md +++ b/docs/reference/basic/show-leds.md @@ -15,12 +15,13 @@ basic.showLeds(` ### Parameters -* ``leds`` - a series of LED on/off states that form an image (see steps below) -* (optional) ``ms`` - [Number](/reference/types/number) - time to wait after displaying image. In blocks, ``ms`` is 400 by default. +* `leds` is a [String](/reference/types/string) that shows which LEDs are on and off. +* `ms` is an optional [Number](/reference/types/number) that shows how many milliseconds to wait after showing a picture. +If you are programming with blocks, `ms` starts out as 400 milliseconds. -### Example - Block Editor +### Example -1. Open the `basic` category and select the `show leds` blocks. +Open the `basic` card in the Block Editor and select the `show leds` blocks. ```blocks basic.showLeds(` @@ -33,7 +34,7 @@ basic.showLeds(` ) ``` -In JavaScript, the led off is represented by a `.` and the led on by a `#` character. +If you are programming in JavaScript, `#` means an LED that is turned on and `.` means an LED that is turned off. ### Lessons diff --git a/docs/reference/basic/show-number.md b/docs/reference/basic/show-number.md index c6f46601..68b18bab 100644 --- a/docs/reference/basic/show-number.md +++ b/docs/reference/basic/show-number.md @@ -8,8 +8,8 @@ basic.showNumber(2, 150) ### Parameters -* **value** is a [Number](/reference/types/number). -* **interval (ms)** is an optional [Number](/reference/types/number). It means the number of milliseconds before sliding the **value** left by one LED each time. Bigger intervals make the sliding slower. +* `value` is a [Number](/reference/types/number). +* `interval` is an optional [Number](/reference/types/number). It means the number of milliseconds before sliding the `value` left by one LED each time. Bigger intervals make the sliding slower. ### Examples: @@ -19,7 +19,7 @@ To show the number 10: basic.showNumber(10) ~~~~ -To show the number stored in the `x` variable: +To show the number stored in a variable: ~~~~blocks let x = 1 @@ -39,8 +39,8 @@ for (let i = 0; i < 6; i++) { ### Other show functions -* use [show string](/reference/basic/show-string) to show a [String](/reference/types/string) with letters on the screen -* use [show animation](/reference/basic/show-animation) to show a group of pictures on the screen, one after another +* Use [show string](/reference/basic/show-string) to show a [String](/reference/types/string) with letters on the screen. +* Use [show animation](/reference/basic/show-animation) to show a group of pictures on the screen, one after another. ### Lessons diff --git a/docs/reference/basic/show-string.md b/docs/reference/basic/show-string.md index c8ef05a5..74427656 100644 --- a/docs/reference/basic/show-string.md +++ b/docs/reference/basic/show-string.md @@ -1,6 +1,6 @@ # Show String -Show a string on the [LED screen](/device/screen) one character at a time (scrolling from left to right). +Show a number on the [LED screen](/device/screen). It will slide left if it is bigger than the screen. ```sig basic.showString("Hello!") @@ -8,18 +8,18 @@ basic.showString("Hello!") ### Parameters -* `text` - a [String](/reference/types/string) -* (optional) `ms` - [Number](/reference/types/number); the time (in milliseconds) before scrolling left by one LED; the larger the number, the slower the scroll +* `text` is a [String](/reference/types/string). It can contain letters, numbers, and punctuation. +* `ms` is an optional [Number](/reference/types/number). It means the number of milliseconds before sliding the [String](/reference/types/string) left by one LED each time. Bigger intervals make the sliding slower. ### Examples: -To display Hello: +To show the word **Hello**: ```blocks basic.showString("Hello") ``` -To display the content of a string variable: +To show what is stored in a [String](/reference/types/string) variable: ```blocks let s = "Hi" @@ -28,8 +28,8 @@ basic.showString(s) ### Other show functions -* use [show number](/reference/basic/show-number) to show a number on the screen -* use [show animation](/reference/basic/show-animation) to show a series of images on the screen +* Use [show number](/reference/basic/show-number) to show a number on the [LED screen](/device/screen). +* Use [show animation](/reference/basic/show-animation) to show a group of pictures on the screen, one after another. ### Lessons