== Creating exercises ==

A Bolt exercise is a PHP script.
Here's an example consisting of a multiple-choice question:
{{{
<?php
echo 'Conifers are so named because:';
bolt_exclusive_choice(
   array(
      'They carry their seeds in cones.'
      'They are cone-shaped.',
      'They originated during the Coniceous era.',
   ),
);
?>
}}}
Each time the question is shown,
the choices are shown in a random order.
The correct choice is the first element of the array.

Here's an example that shows an image;
a correct answer is a click in the indicated subrectangle.
{{{
<?php
echo "Click on the dog's nose:<p>";
bolt_image_rect(
   'dog.jpg',
   array(100, 60, 110, 70)
);
?>
}}}

Bolt supplies functions for other types of questions,
such as inclusive multiple-choice and fill-in-the-blank.
An exercise can include multiple questions.


== Course documents ==

The structure of a Bolt course is defined by a [RFC:4627 JSON] document.
Here's an example of a course with two lessons followed by an exercise:
{{{
{
   "name": "Identifying Sierra Conifers",
   "description: "Learn to identify the major conifers of California's Sierra Nevada",
   "items": [
      {
          "type": "lesson",
          "name": "Introduction",
          "file": "intro.html"
      },
      {
          "type": "lesson",
          "name": "The Linnaean hierarchy",
          "file": "linnaean.html"
      },
      {
          "type": "exercise",
          "file": "linnaean.php"
      }
   ]
}
}}}

Course items can be grouped into '''sets'''; for example:

{{{
{
   "type": "set",
   "show_n": 1,
   "order": "random",
   "items": {
      {
      ...
      }
   }
}
}}}

The attributes of a set include:

 * show_n: the number of items in the set to show
 * order: whether to show the items sequentially or randomly

Items (lessons, exercises, and sets) can include '''properties''', e.g.:

{{{
{
   "type": "lesson",
   "name": "The Linnaean hierarchy",
   "file": "linnaean.html"
   "properties": {
      "verbal_level": 12,
      "detail_level": 0.8
   }
},
}}}

When Bolt has a choice of items (e.g. when it encounters a set from which a
single item is to be shown) it calls, for each item, a course-supplied
'''matchmaking function''', passing to it the student object
(which includes demographics such as age)
and the item's properties (represented as a PHP object).
The matchmaking function returns a number representing the estimated
effectiveness of that item for that student,
and Bolt chooses the item with the highest value.