Merge branch 'master' into test-synthutils.js

Debugging.md

@@ -35,77 +35,96 @@ you will make mistakes along the way. Music Blocks provides a number
 of mechanisms, reviewed below, to help you explore ideas and find
 mistakes.
 
-## 1. Clicking on an individual stack of blocks
+## <a>TABLE OF CONTENTS</a>
+
+1. [Clicking on an Individual Stack of Blocks](#1-clicking-on-an-individual-stack-of-blocks)
+2. [Print and Comment Blocks](#2-print-and-comment-blocks)
+3. [Status Widget](#3-status-widget)
+4. [Playback Modes](#4-playback-modes)
+5. [Show and Hide blocks](#5-show-and-hide-blocks)
+6. [Browser Console](#6-browser-console)
+
+## <a>1. Clicking on an Individual Stack of Blocks</a>
 
 The *Play* button (in top left corner) will run all of the *Start*
 blocks simultaneously. (Every Music Blocks project has at least one
 *Start* block). But you can also run an individual stack of code by
 clicking on a stack. This lets you test and debug small sections of
 code, or, as in the example below, you can play a single voice by
 clicking on one of the *Start* blocks or single phase by clicking on
-one of the *Action* blocks.
+one of the *Action* blocks. [RUN LIVE](https://musicblocks.sugarlabs.org/index.html?id=1732463245651983&run=True)
 
-![alt tag](https://github.com/sugarlabs/musicblocks/blob/master/images/startblocks_debug_guide.png "Start blocks")
+![alt tag](https://github.com/sugarlabs/musicblocks/blob/master/images/startblocks_debug_guide.png "Start Blocks")
 
-## 2. Print and Comment blocks
+## <a>2. Print and Comment Blocks</a>
+
+[Back to Table of Contents](#table-of-contents)
 
 The *Print* block (found on the *Extras* palette) can be used to print
 a message while running a program. It is useful to determine if a
 section of code is being executed when expected or if a box or
 parameter contains an expected value.
 
-![alt tag](https://github.com/sugarlabs/musicblocks/blob/master/images/print_example2_debug_guide.png "Print blocks")
+![alt tag](https://github.com/sugarlabs/musicblocks/blob/master/images/print_example2_debug_guide.png "Print Block")
 
 The *Print* block is used to display the number of whole notes played,
 in this case, `1/4 + 1/4 + 1/2`, which adds up to `1`, which is
-displayed at the top of the browser window.
+displayed at the top of the browser window. [RUN LIVE](https://musicblocks.sugarlabs.org/index.html?id=1732474452574359&run=True)
 
 The *Comment* block (also found on the *Extras* palette) is similar to
 the *Print* block, except it only prints a message when the program is
 being run in *Playback Slow* mode (See below). Comments are also
-written to the browser console.
+written to the browser console. [RUN LIVE](https://musicblocks.sugarlabs.org/index.html?id=1732825564345176&run=True)
+
+![Comment Block](./images/Comment_block_DebuggingMd.svg "Comment Block")
 
-## 3. Status widget
+## <a>3. Status Widget</a>
 
-![alt tag](https://rawgithub.com/sugarlabs/musicblocks/master/guide/status1.svg "given Music block")
+[Back to Table of Contents](#table-of-contents)
 
-![alt tag](https://github.com/sugarlabs/musicblocks/blob/master/images/status_example_debug_guide.png "status in tabular form")
+![Status Widget Block](./images/Status_widget_debuggingMd.svg "Status Widget Block")
+
+![alt tag](https://github.com/sugarlabs/musicblocks/blob/master/images/status_example_debug_guide.png "Status in tabular form")
 
 The *Status widget* is a tool for inspecting the status of Music
 Blocks as it is running. By default, the key, BPM, and volume are
 displayed. Also, each note is displayed as it is played. There is one
-row per voice in the status table.
+row per voice in the status table. [RUN LIVE](https://musicblocks.sugarlabs.org/index.html?id=1732541757152077&run=True)
 
 Additional *Print* blocks can be added to the *Status* widget to
 display additional music factors, e.g., duplicate, transposition,
 skip, [staccato](#MORE-TRANSFORMATIONS),
 [slur](#MORE-TRANSFORMATIONS), and [graphics](#GRAPHICS) factors,
 e.g., x, y, heading, color, shade, grey, and pensize.
 
-![alt tag](https://rawgithub.com/sugarlabs/musicblocks/master/guide/status3.svg "additional programming within the Status block")
+![Additional Programming within the Status Widget Block](./images/Status_Widget_additional_programming_DebuggingMd.svg "Additional Programming within the Status Widget Block")
 
 You can do additional programming within the status block. In the
 example above, `whole notes played` is multiplied by `4` (e.g. quarter notes)
-before being displayed.
+before being displayed. [RUN LIVE](https://musicblocks.sugarlabs.org/index.html?id=1732553086132345&run=True)
+
+## <a>4. Playback Modes</a>
 
-## 4. Playback modes
+[Back to Table of Contents](#table-of-contents)
 
 Clicking on the Play button will play your program at full speed.
 (It will also hide the blocks while the program runs, which improves
 performance.) But there are two other playback modes.
 
 On the Secondary Menu, there are two other Play buttons.
 
-During Playback Slow mode the program will pause between the execution
+During *Playback Slow* mode the program will pause between the execution
 of each block and the block being executed will be highlighted. This is
 useful for following program flow, ensuring that the sequence of blocks
 being executed is what you expect. In addition, the value stored in any
 box or parameter is displayed on the block as the program runs, so you
 can "inspect" program elements as the program runs.
 
-Run Step by Step advances one block per button press.
+*Run Step by Step* advances one block per button press.
 
-## 5. Show and Hide blocks
+## <a>5. Show and Hide blocks</a>
+
+[Back to Table of Contents](#table-of-contents)
 
 The *Show* and *Hide* blocks (found on the *Extras* palette) are
 useful for setting
@@ -117,7 +136,7 @@ gets to the *Show* block. Then the blocks are displayed and
 run in *Playback Slow* mode. When the *Hide* block is encountered, the
 blocks are hidden and the program resumes running at full speed.
 
-## 6. Browser console
+## <a>6. Browser Console</a>
 
 As Music Blocks runs, some debugging information is written to the
 browser console, such as the notes being played and comments (See the
@@ -127,3 +146,5 @@ browser console, such as the notes being played and comments (See the
 ![alt tag](https://github.com/sugarlabs/musicblocks/blob/master/images/browserconsole_debug_guide.png "Console blocks")
 
 Shown above is the console output from three notes: `sol mi sol`.
+
+[Back to Table of Contents](#table-of-contents)

Music_Blocks_for_Snap_Users.md

@@ -78,7 +78,7 @@ like Snap, you can change the size of the blocks.
 
 ### Operators and Predicates
 
-Infix vs Prefix
+**Infix vs Prefix**
 
 Snap uses Infix notation for its operators:
 
@@ -106,7 +106,8 @@ In Snap, you make variables explicitly.
 ![Snap Variables](./images/snap/snap-variables.png)
 
 The Set To and Change By commands are specified through pull-down menus.
-Store in Box
+
+**Store in Box**
 
 In Music Blocks, we use an analogy of a shoe box. You put something
 into a box and then reference the thing by the name you have given to
@@ -151,7 +152,7 @@ to “12”) to store the possible outcome of rolling two dice. I store in
 the box named “box” the sum of two random numbers between 1 and 6, so
 the box named “box” has a number between 2 and 12. Then I increment
 the box named for the number stored in “box” by one. Later in the
-program I make a bar chart showing the value stored in each box.
+program, I make a bar chart showing the value stored in each box.
 
 ![Music Blocks Dice](./images/snap/dice.png)
 
@@ -223,7 +224,7 @@ Stitch, since the embroidery machines only have one needle (“single
 threaded”). But in music, we often have more than one voice or
 instrument. You get a separate “thread” for each Start block.
 
-For example, we can implement a simple mirror paint by using four Start blocks.
+For example, we can implement a simple mirror paint by using four Start blocks. [RUN LIVE](https://musicblocks.sugarlabs.org/index.html?id=1732171217345259&run=True)
 
 ![Music Blocks Start Blocks](./images/snap/multiple-mouse.png)
 
@@ -474,13 +475,13 @@ multiple Note blocks. The actions are used in combination to create
 music.
 
 Here is an example of a canon (Frère Jacques), using four voices, each
-sharing the actions.
+sharing the actions. [RUN LIVE](https://musicblocks.sugarlabs.org/index.html?id=1732463245651983&run=True)
 
 ![Frere Jacques](./images/snap/frere-jacques.png)
 
 ## For further information
 
-[Music Blocks README](./README.md) exxplains where to find Music Blocks.
+[Music Blocks README](./README.md) explains where to find Music Blocks.
 
 [Using Music Blocks](./documentation/README.md) has basic instructions.
 

README.md

@@ -103,9 +103,11 @@ Linux systems, the `python3` command is not bound to python. You may
 need to perform a `sudo apt install python-is-python3` on Debian-like
 distros, or equivalent on others.)
 
-4. After cloning the musicblocks repository, run
+4. After cloning the musicblocks repository, you can choose one of two methods to start a local server: using Python or using npm
 
-    for _Linux_ and _macOS_:
+   **Using Python**
+
+   for _Linux_ and _macOS_:
 
     ```bash
     python -c "import os, sys; os.system('python -m SimpleHTTPServer 3000 --bind 127.0.0.1') if sys.version_info.major==2 else os.system('python -m http.server 3000 --bind 127.0.0.1')"
@@ -117,17 +119,29 @@ distros, or equivalent on others.)
     python -c "import os, sys; os.system('python -m SimpleHTTPServer 3000') if sys.version_info.major==2 else os.system('python -m http.server 3000 --bind 127.0.0.1')"
     ```
 
-    If you have `npm` installed, simply run `npm run serve` for Linux
-    and macOS, and `npm run winserve` for Windows.
+
+    **Using npm**
+
+    for _Linux_ and _macOS_:
+
+    ```bash
+    npm run serve
+    ```
+
+    for _Windows_:
+
+    ```bash
+    npm run winserve
+    ```
 
     **NOTE:** _Make sure you can run either `python` or `py` from your
     terminal, to launch the Python prompt._
 
-5. You should see a message `Serving HTTP on 127.0.0.1 port 3000
+6. You should see a message `Serving HTTP on 127.0.0.1 port 3000
 (http://127.0.0.1:3000/) ...` since the HTTP Server is set to start
 listening on port 3000.
 
-6. Open your favorite browser and visit `localhost:3000` or `127.0.0.1:3000`.
+7. Open your favorite browser and visit `localhost:3000` or `127.0.0.1:3000`.
 
 **NOTE:** _Use `ctrl + c` or `cmd + c` to quit the HTTP Server to avoid
 `socket.error:[Errno 48]`_.