Changes between Version 38 and Version 39 of BoltRef

Timestamp:

Oct 24, 2008, 4:13:21 PM (16 years ago)

Author:

davea

Comment:

--

BoltRef

@@ -164 +164 @@
 === Select ===
 
-The '''select''' structure takes a set of units and a 'value function',
-which returns the predicted benefit of showing the unit to the student.
+The '''select''' structure takes a set of units and a 'value function'.
 The unit for which this value is greatest is shown.
 The value function may be partly or entirely random.
@@ -175 +174 @@
 
 {{{
-<?php
+select(
+   name('name'),
+   valuator('func_name'),
+   unit1,
+   unit2,
+   ...
+);
+}}}
+Example:
+{{{
 function value($student, $unit) {
     return abs($student->verbal_level - $unit->verbal_level);
 }
 
-return select(
+select(
     name('course'),
     valuator('value'),
     lesson(
-        name('lesson 1'),
         filename('bolt_sample_lesson1.php')
     ),
     lesson(
-        name('lesson 2'),
         filename('bolt_sample_lesson2.php')
     ),
 );
-?>
-
-}}}
-
+}}}
 
 
@@ -202 +205 @@
 The '''random''' control structure selects randomly (without replacement) from a set of units.
 {{{
-<?php
-return random(
+random(
+    name('name'),
+    [ number(N), ]
+    unit1,
+    unit2,
+    ...
+);
+}}}
+ '''number''' :: how many units are to be shown (default: all of them).
+
+Example:
+{{{
+random(
     name('foobar'),
     number(2),
     lesson(
-        name('lesson 1'),
         filename('bolt_sample_lesson1.php')
     ),
     lesson(
-        name('lesson 2'),
         filename('bolt_sample_lesson2.php')
     ),
     lesson(
-        name('lesson 3'),
         filename('bolt_sample_lesson3.php')
     ),
@@ -221 +232 @@
 ?>
 }}}
-
-If 'number()' is given, that many units are shown; the default is to show all the units.
 
 The 'without replacement' applies across multiple visits to the same structure
@@ -229 +238 @@
 === Exercise set ===
 
-The 'exercise_set' structure specifies a set of exercises and a value 'number' (default one).
-This number of exercises is chosen randomly (without replacement) and administered.
+The 'exercise_set' structure specifies a set of exercises.
+A number of exercises is chosen randomly (without replacement) and administered.
 
 The navigation links on the answer page of the last exercise
 may allow the student to review for and/or repeat the exercise set (see below).
 
-Exercise sets may not be nested.
+{{{
+exercise_set(
+    name('name'),
+    [ number(N), ]
+    exercise1,
+    exercise2,
+    ...
+    [ callback('my_func'), ]
+    [ repeat-spec1, ]
+    [ repeat-spec2, ]
+    [ ... ]
+    [ refresh-spec ]
+);
+}}}
+
+ '''number''' :: the number of exercises to administer.
+ '''callback''' :: a function to call on the completion of the exercise set.  It will be called as
+{{{
+callback($student, $score);
+}}}
+where $student is the student record and $score [0..1] is the score.
+ '''repeat-spec''': A repeat specification (see below).
+ '''refresh-spec''': A refresh specification (see below).
 
 Example:
@@ -241 +272 @@
 exercise_set(
     name('exer_set'),
-    number(1),
     exercise(
         name('exercise 1'),
@@ -250 +280 @@
         filename('file_1.php')
     ),
-    callback('my_func'),
     repeat(.3, basic_review(), REVIEW),
     repeat(.7, int_review(), REVIEW|REPEAT),
     repeat(1, null, REPEAT|NEXT),
-    refresh(array(7, 14, 28))
-);
-}}}
-
- '''callback()''' specifies a function to be called when the exercise set is completed.
-This function is called with the following arguments:
-{{{
-function($student, $score);
-}}}
-where $student is the student record and $score [0..1] is the score.
-== Exercise review and repeat ==
+    refresh(array(7, 14, 28)) 
+);
+}}}
+
+=== Repeat specification ===
 
 The "repeat" items in an exercise set determine the student's options
@@ -301 +324 @@
 || 1 || continue ||
 
-== Memory refresh ==
+=== Refresh specification ===
 
 If a '''refresh()''' argument is given to exercise_set(),
@@ -315 +338 @@
 partway through refresh for set B.
 
-=== Changing course documents ===
+== Changing course documents ==
 
 Course documents can change over time.