add more markup to tutorial objectives prose (#1412)

Closes #1411

data/entities.yaml

@@ -497,7 +497,7 @@
   description:
   - A robot with a boat equipped can float on top of water without drowning.
   - |
-    Note: most devices are automatically equipped on robots that
+    **NOTE:** most devices are automatically equipped on robots that
     will require them; but this doesn't work in the case of boats since floating is not
     associated with any particular command.  To manually ensure a boat is equipped on
     a robot, just add the special command `require "boat"` to the robot's program.
@@ -765,7 +765,7 @@
   - Equipping treads on a robot allows it to move and turn.
   - The `move` command moves the robot forward one unit.
   - |
-    Example:'
+    Example:
     ```
     move; move; // move two units
     ```

data/scenarios/Challenges/Ranching/gated-paddock.yaml

@@ -142,7 +142,7 @@ objectives:
           create specialDrill;
           equip specialDrill;
 
-          // NOTE: System robots can walk on water
+          // **NOTE:** System robots can walk on water
           // so we only need this if we want to
           // demo the algorithm with a player robot.
       //    create "boat";

data/scenarios/Tutorials/bind2.yaml

@@ -13,7 +13,7 @@ objectives:
       - |
         Build a robot to retrieve and restore the mystery artifact to its proper place!
       - |
-        Note: If you find yourself stuck, you can select "Start over" from
+        **NOTE:** If you find yourself stuck, you can select "Start over" from
         the "Quit" (**Ctrl+Q**) dialog.
     condition: |
       try {
@@ -38,7 +38,7 @@ objectives:
         For example, `grab` has type `cmd text`{=type}, and returns the name of the
         grabbed entity as a text value.
       - |
-        To use the result of a command later, you need "bind notation", which
+        To use the result of a command later, you need _bind notation_, which
         consists of a variable name and a leftwards-pointing arrow
         before the command.  For example:
       - |

data/scenarios/Tutorials/build.yaml

@@ -15,10 +15,10 @@ objectives:
         where in place of `COMMANDS`{=snippet} you write the sequence
         of commands for the robot to execute (separated by semicolons).
       - |
-        Build a robot to harvest the `"flower"` and place it next
-        to the water.
+        Build a robot to harvest the `flower`{=entity} and place it next
+        to the `water`{=entity}.
       - |
-        TIP: Newly built robots start out facing the same
+        **TIP:** Newly built robots start out facing the same
         direction as their parent, which in the tutorials will always be north.
     condition: |
       try {

data/scenarios/Tutorials/conditionals.yaml

@@ -42,13 +42,13 @@ objectives:
         must also be in curly braces: the type of `build`
         is `{cmd a} -> cmd robot`{=type}.
       - |
-        TIP: Note that `if` requires a `bool`{=type}, not a `cmd bool`{=type}!  So you cannot directly say
+        **TIP:** Note that `if` requires a `bool`{=type}, not a `cmd bool`{=type}!  So you cannot directly say
         `if (ishere "very small rock") {...} {...}`{=snippet}.
         Instead you can write `b <- ishere "very small rock"; if b {...} {...}`{=snippet}.
         You might enjoy writing your own function of
         type `cmd bool -> {cmd a} -> {cmd a} -> cmd a`{=type} to encapsulate this pattern.
       - |
-        TIP: the two branches of an `if` must have the same type. In particular,
+        **TIP:** the two branches of an `if` must have the same type. In particular,
         `if ... {grab} {}`{=snippet} is not
         allowed, because `{grab}` has type `{cmd text}`{=type} whereas `{}` has type `{cmd unit}`{=type}.
         In this case `{grab; return ()}` has the right type.

data/scenarios/Tutorials/craft.yaml

@@ -10,13 +10,13 @@ objectives:
   - goal:
       - Robots can use the `make` command to make things, as long as
         they have a `workbench`{=entity} and the proper ingredients.  For
-        example, `make "circuit"` will make a circuit.
-      - Your base has a few trees in its inventory. Select them to see the
+        example, `make "circuit"` will make a `circuit`{=entity}.
+      - Your base has a few `tree`{=entity}s in its inventory. Select them to see the
         available recipes.
       - Your goal is to make a `branch predictor`{=entity}, so you will have to make
-        some `"branch"`es first.
+        some `branch`{=entity}es first.
       - |
-        Note: when used after opening quotes in the REPL, the Tab key can cycle through
+        **NOTE:** when used after opening quotes in the REPL, the Tab key can cycle through
         possible completions of a name. E.g., type:
       - |
         `> make "br[Tab][Tab]`{=snippet}

data/scenarios/Tutorials/def.yaml

@@ -4,9 +4,9 @@ description: |
   Learn how to define new commands.
 objectives:
   - goal:
-      - Your goal is to build a robot to fetch the flower growing in the
+      - Your goal is to build a robot to fetch the `flower`{=entity} growing in the
         upper right and bring it back to you; you win the challenge when the base
-        has a flower in its inventory.
+        has a `flower`{=entity} in its inventory.
       - |
         However, it would be extremely tedious to simply type out all the individual
         `move` and `turn` commands required.  Your base has a `dictionary`{=entity} device
@@ -20,15 +20,15 @@ objectives:
         use of new definitions, it should be possible to complete this challenge
         in just a few lines of code.
       - |
-        TIP: your base is at coordinates (0,0), and the flower is at (16,4), which
+        **TIP:** your base is at coordinates `(0,0)`, and the `flower`{=entity} is at `(16,4)`, which
         you can confirm by clicking in the world map panel. When you click on a cell,
         its contents and coordinates are shown in the lower left.
       - |
-        TIP: the type annotation in a definition is optional.  You could also write
+        **TIP:** the type annotation in a definition is optional.  You could also write
         `def m4 = move; move; move; move end`, and Swarm would infer
         the type of `m4`{=snippet}.
       - |
-        TIP: writing function definitions at the prompt is annoying.
+        **TIP:** writing function definitions at the prompt is annoying.
         You can also put definitions in a `.sw`{=path} file and load it
         with the `run` command. Check out
         https://github.com/swarm-game/swarm/tree/main/editors

data/scenarios/Tutorials/equip.yaml

@@ -13,7 +13,7 @@ objectives:
         Try typing `build {}` - you should get an error telling you that you
         need to equip a `3D printer`{=entity}.
       - |
-        Fortunately, there is a 3D printer lying nearby.  Go `grab` it, then
+        Fortunately, there is a `3D printer`{=entity} lying nearby.  Go `grab` it, then
         `equip` it with `equip "3D printer"`.
       - |
         You win by building your first robot:

data/scenarios/Tutorials/farming.yaml

@@ -6,7 +6,8 @@ objectives:
   - id: get_many_lambdas
     teaser: Get 256 lambdas
     goal:
-      - Lambdas are an essential item for building robots, but they
+      - |
+        `lambda`{=entity}s are an essential item for building robots, but they
         are somewhat rare in the wild.  Therefore, it makes sense to farm
         them in order to create a reliable supply.
       - |
@@ -20,13 +21,15 @@ objectives:
         ```
         def forever = \c. c ; forever c end
         ```
-      - Your goal is to acquire 256 lambdas.  Of course, in order to
+      - |
+        Your goal is to acquire 256 `lambda`{=entity}s.  Of course, in order to
         accomplish this in a reasonable amount of time, it makes sense to plant
-        a field of lambdas and then program one or more robots to
+        a field of `lambda`{=entity}s and then program one or more robots to
         harvest them in an automated way.
-      - "TIP: the `ishere` command can be used to test for the presence of a
-        (fully-grown) lambda, and the `has` command can be used to test whether
-        a robot has a lambda in its inventory."
+      - |
+        **TIP:** the `ishere` command can be used to test for the presence of a
+        (fully-grown) `lambda`{=entity}, and the `has` command can be used to test whether
+        a robot has a `lambda`{=entity} in its inventory.
     condition: |
       try {
         as base {

data/scenarios/Tutorials/grab.yaml

@@ -4,9 +4,9 @@ description: |
   Learn how to interact with the world by grabbing entities.
 objectives:
   - goal:
-      - Previously you learned how to make new things (like a branch predictor) from ingredients.
+      - Previously you learned how to make new things (like a `branch predictor`{=entity}) from ingredients.
         Now you will learn how to obtain the ingredients you need.
-      - There are some trees ahead of your robot; `move` to each one and `grab` it.
+      - There are some `tree`{=entity}s ahead of your robot; `move` to each one and `grab` it.
       - You can learn more by reading about the grabber device in your
         inventory.  Remember, if the description does not fit in the
         lower left info box, you can either hit **Enter** to pop out the

data/scenarios/Tutorials/lambda.yaml

@@ -5,7 +5,7 @@ description: |
 objectives:
   - goal:
       - Your goal in this challenge is to send a robot to grab the
-        flower in the lower right (you don't need to bring it back).
+        `flower`{=entity} in the lower right (you don't need to bring it back).
       - |
         The path looks complex, but if you study it, you will see that it
         has a lot of structure.  In particular, there are many parts of

data/scenarios/Tutorials/move.yaml

@@ -9,7 +9,7 @@ objectives:
       - Robots can use the `move` command to move forward one unit
         in the direction they are currently facing.
       - To complete this challenge, move your robot two spaces to the right,
-        to the coordinates `(2,0)` marked with the purple flower.
+        to the coordinates `(2,0)` marked with the purple `flower`{=entity}.
       - Note that you can chain commands with semicolon, `;`{=snippet}.
       - You can open this popup window at any time to remind yourself of the goal
         using **Ctrl+G**.
@@ -23,11 +23,13 @@ objectives:
       - |
         Previously you could move twice by chaining the move command:
       - |
+        ```
         move; move
+        ```
       - To reuse that command without having to retype it press the upward
         arrow on your keyboard. This will allow you to select previous commands.
       - Ahead of you is a six steps long corridor. Move to its end, i.e. the
-        coordinates `(8,0)` marked with the second purple flower.
+        coordinates `(8,0)` marked with the second purple `flower`{=entity}.
       - You can open this popup window at any time to remind yourself of the goal
         using **Ctrl+G**.
     condition: |
@@ -64,7 +66,7 @@ objectives:
   - goal:
       - Good job! You are now ready to move and turn on your own.
       - To complete this challenge, move your robot to the northeast corner,
-        to the coordinates `(8,8)` marked with one flower.
+        to the coordinates `(8,8)` marked with one `flower`{=entity}.
       - Remember you can press the upward arrow on your keyboard to select previous commands.
       - You can open this popup window at any time to remind yourself of the goal
         using **Ctrl+G**.

data/scenarios/Tutorials/place.yaml

@@ -11,23 +11,23 @@ objectives:
   - goal:
       - Previously you learned how to plunder a plentiful forest for wood.
         Now you will learn how to plant trees to obtain as much wood as you need.
-      - There is a fast-growing tree (called `"spruce"`) ahead of you.  You could `grab`
+      - There is a fast-growing tree (called `spruce`{=entity}) ahead of you.  You could `grab`
         it as before, but you now have a new device called a `harvester`{=entity}.
         If you `harvest` a tree rather than `grab` it, a new tree will grow in its
         place after some time.
       - You can also place items from your inventory on the ground
         below you using the `place` command.
       - |
         Using these commands in conjunction, you can plant new growable entities by
-        placing and then harvesting them.  For example, to plant a new spruce seed
+        placing and then harvesting them.  For example, to plant a new `spruce`{=entity} seed
         you can write:
         ```
         place "spruce"; harvest
         ```
-      - Your goal is to collect 6 spruce trees.  You can speed this up
+      - Your goal is to collect 6 `spruce`{=entity} trees.  You can speed this up
         by planting more trees.
       - |
-        TIP: You can get a sneak peak at a feature we will explain later and type:
+        **TIP:** You can get a sneak peak at a feature we will explain later and type:
         ```
         def t = move; place "spruce"; harvest; end
         ```

data/scenarios/Tutorials/require.yaml

@@ -19,7 +19,7 @@ objectives:
       - Your goal is to pick a flower on the other side of the river and
         bring it back to your base.  You win when the base has a
         `periwinkle`{=entity} flower in its inventory.
-      - "Hint: robots will drown in the water unless they have a `boat`{=entity} device
+      - "Hint: robots will drown in the `water`{=entity} unless they have a `boat`{=entity} device
         equipped!"
     condition: |
       try {

data/scenarios/Tutorials/requireinv.yaml

@@ -13,7 +13,7 @@ objectives:
       - For example, `build {require 10 "flower"; move; move}` would
         build a robot with 10 `flower`{=entity}s in its inventory.
       - Your goal in this challenge is to cover the entire 4x4 gray area
-        with rocks!
+        with `rock`{=entity}s!
       - |
         Remember that you can define commands to simplify your task, for example:
         ```

data/scenarios/Tutorials/scan.yaml

@@ -7,7 +7,7 @@ objectives:
       - When you land on an alien planet, all the entities in the
         world will be unfamiliar to you, but you can learn what they are using
         the `scan` command, enabled by a `scanner`{=entity} device.
-      - Send one or more robots to move next to some of the unknown entities (marked as ?),
+      - Send one or more robots to move next to some of the unknown entities (marked as "?"),
         scan them (with something like `scan forward` or `scan north`), and then return
         to the base and execute `upload base`.
       - For more information about the `scan` and `upload` commands, read

data/scenarios/Tutorials/type-errors.yaml

@@ -13,7 +13,7 @@ objectives:
       - |
         `turn move`{=snippet}
       - |
-        `place tree`{=snippet} (without double quotes around "tree")
+        `place tree`{=snippet} (without double quotes around `tree`{=snippet})
       - |
         `move move`{=snippet}
       - The last expression might give the most confusing error.

data/scenarios/Tutorials/types.yaml

@@ -12,7 +12,7 @@ objectives:
         its type will be displayed in gray text at the top right of the window.
       - For example, if you try typing `move`, you can see that it has
         type `cmd unit`{=type}, which means that `move` is a command which
-        returns a value of the unit type (also written `()`).
+        returns a value of the `unit`{=type} type (also written `()`).
       - As another example, you can see that `turn` has type `dir -> cmd unit`{=type},
         meaning that `turn` is a function which takes a direction as input
         and results in a command.

data/scenarios/Tutorials/world101.yaml

@@ -21,8 +21,8 @@ objectives:
         via the `run` command.  See
         https://github.com/swarm-game/swarm/tree/main/editors
         for help configuring your editor with support for swarm-lang.
-      - Your first task is to collect three or more trees. You can
-        remind yourself of the available commands using F4.
+      - Your first task is to collect three or more `tree`{=entity}s. You can
+        remind yourself of the available commands using **F4**.
     condition: |
       try {
         n <- as base {count "tree"};
@@ -43,15 +43,15 @@ objectives:
       - Now that you have a harvester, you can use `harvest` instead of `grab`
         whenever you pick up a growing item (check for the word "growing" at the
         top of the item description), to leave behind a seed that will regrow.
-      - "TIP: since you only have a single harvester device for now, whenever you
+      - "**TIP:** since you only have a single harvester device for now, whenever you
         send out a robot to harvest something, try programming it to come back
         to the base when it is done.  Then, execute `salvage` to get the harvester
         back, so you can reuse it in another robot later."
       - One of the next things you will probably want is a `lambda`{=entity}, so you can
         define and use parameterized commands.  Scan some things and use
         the process of elimination to find one.  Since lambdas regrow,
         once you find one, try getting it with `harvest`.
-      - "TIP: remember that you can click on cells in the world to see their
+      - "**TIP:** remember that you can click on cells in the world to see their
         coordinates."
     condition: |
       try { as base {has "lambda"} } {return false}