Changes between Version 37 and Version 38 of BoltRef

Timestamp:

Oct 24, 2008, 3:58:59 PM (16 years ago)

Author:

davea

Comment:

--

BoltRef

@@ -9 +9 @@
  * A '''course document''' describing the order in which lessons and exercises are shown.
 
-To use Bolt:
+== Installing Bolt ==
+
+If you already have a BOINC or Bossa project, you already have Bolt.
+Otherwise:
  * [MakeProject create a BOINC project]; use '''make_project --web_only''' so that you don't have to compile any (irrelevant) programs. Similarly, you can [ToolUpgrade upgrade Bolt software] using '''upgrade --web_only'''.
+
+Then:
  * In the boinc/db directory, run
 {{{
@@ -86 +91 @@
 image_rect(
    image_filename,
-   array(100, 60, 110, 70)
+   array(xmin, xmax, ymin, ymax)
 );
 ?>
 }}}
 This specifies a question where the student clicks on an image;
-a correct answer is a click in the indicated subrectangle.
+a correct answer is a click in the indicated subrectangle
+((0,0) is the upper left corner of the image).
 
 In addition to calling these functions,
-an exercise script can put text before or after the questions.
+an exercise script can intersperse text among the questions.
 Example:
 {{{
@@ -111 +117 @@
 
 The structure of a Bolt course is defined by a PHP script called a '''course document'''.
-The script calls Bolt API functions to create a hierarchy of "units" of two types:
-
- * '''Basic units''': lessons and exercises
- * '''Control structures''' representing sets of units, together with rules the govern their use.
-
-The function '''lesson()''' specifies a lesson.
-For example, the following course consists of a single lesson:
+The script calls Bolt API functions to create a hierarchy of '''units'''.
+The API is as follows.
+
+=== Lesson ===
+
+To specify a lesson:
+{{{
+lesson(
+    filename('lesson_1.php?arg=4'),
+    [ title('The ecology of a conifer forest'), ]
+);
+}}}
+
+The parameters are:
+
+ '''filename''' ::  the file containing lesson content, optionally followed by a query string. The query string specified in filename() is passed in a global variable '''$bolt_query_string''', rather than in $_GET. To parse it, use
+{{{
+parse_str($bolt_query_string);
+}}}
+ '''title''' :: a name shown to students 
+
+=== Exercise ===
+
+To specify an exercise:
+{{{
+exercise(
+    filename('bolt_sample_exercise1.php')
+    [ title('The ecology of a conifer forest'), ]
+);
+}}}
+
+The filename and title parameters are the same as for '''lesson()'''.
+
+=== Sequence ===
+
+A 'sequence' unit specifies a set of units that are shown in sequence:
+{{{
+sequence(
+    name('course'),
+    unit1,
+    unit2,
+    ...
+);
+}}}
+
+=== 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 unit for which this value is greatest is shown.
+The value function may be partly or entirely random.
+
+This structure can be used to implement
+ * "experiments" where different lessons are compared;
+ * "adaptive courses" where different lessons are shown to different types of students.
+or a mixture of the two.
+
 {{{
 <?php
-return lesson(
-    name('lesson 1'),
-    title('The ecology of a conifer forest'),
-    filename('lesson_1.php?arg=4'),
-    reading_level(11.0),
-    detail_level(.5)
+function value($student, $unit) {
+    return abs($student->verbal_level - $unit->verbal_level);
+}
+
+return select(
+    name('course'),
+    valuator('value'),
+    lesson(
+        name('lesson 1'),
+        filename('bolt_sample_lesson1.php')
+    ),
+    lesson(
+        name('lesson 2'),
+        filename('bolt_sample_lesson2.php')
+    ),
 );
 ?>
-}}}
-
-The parameters of the lesson are:
-|| name || the "logical name", used as an internal identifier but not visible to students; see "Names and state" below ||
-|| title || a name shown to students ||
-|| filename || the file containing lesson content, optionally followed by a query string. ||
-|| reading_level, detail_level || optional attributes of the lesson ||
-
-The query string specified in filename() is passed in a global variable $bolt_query_string,
-rather than in $_GET.
-To parse it, use
-{{{
-parse_str($bolt_query_string);
-}}}
-
-Similarly, '''exercise()''' specifies an exercise:
-{{{
-<?php 
-return exercise(
-    name('exercise 1'),
-    filename('bolt_sample_exercise1.php')
+
+}}}
+
+
+
+=== Random ===
+
+The '''random''' control structure selects randomly (without replacement) from a set of units.
+{{{
+<?php
+return 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')
+    ),
 );
 ?>
 }}}
 
-There are various control structures; see below.
-The simples one is a 'sequence',
-which specifies a set of units that are shown in sequence.
-Here's an example of a course with two lessons followed by an exercise:
-{{{
-<?php
-return sequence(
-    name('course'),
-    lesson(...),
-    lesson(...),
-    exercise(...)
-);
-?>
-}}}
+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
+(e.g. because of review or refresh).
+
+=== 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 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.
+
+Example:
+{{{
+exercise_set(
+    name('exer_set'),
+    number(1),
+    exercise(
+        name('exercise 1'),
+        filename('file_1.php')
+    ),
+    exercise(
+        name('exercise 1'),
+        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 ==
+
+The "repeat" items in an exercise set determine the student's options
+to review for and repeat the exercise set.
+(
+Each repeat item is a function call of the form
+{{{
+repeat(grade_threshold, review_unit, nav_flags);
+}}}
+The arguments are:
+ * grade_threshold: the highest grade to which this item applies
+ * review_unit: a unit that reviews the material assessed by for the exercise set.
+ * nav_flags: a bitmask determining which navigation options will be presented:
+  * REVIEW: show the review units, then repeat the exercise set
+  * REPEAT: repeat exercise set immediately
+  * NEXT: continue without repeating the exercise set
+
+A student's score on an exercise set is the average score of the selected exercises.
+Call this Y;
+the "selected repeat item" is the one with the least X such that Y < X.
+
+If there is no such repeat item, the student is not given an option
+to repeat the exercise set; i.e., they see only a Next button.
+
+Otherwise let R be the selected repeat item.
+If R.repeat_optional is true, a Next button is shown.
+If R.review_optional is true, a "Repeat" button is shown.
+If R.review_unit is present, a "Review" button is shown.
+
+Thus, in the example above, the student's options are:
+
+|| grade || options ||
+|| [0, .3) || review and repeat exercise ||
+|| [.3, .7) || review and repeat exercise, or repeat exercise ||
+|| [.7, 1) || repeat exercise, or continue ||
+|| 1 || continue ||
+
+== Memory refresh ==
+
+If a '''refresh()''' argument is given to exercise_set(),
+then when the set is completed by a student it is added to
+a "refresh schedule".
+Each element in a refresh schedule specifies
+The intervals (in days) are given as arguments to refresh().
+
+At a given point, one or more exercise sets may be due for refresh.
+The student may choose any of them to view.
+Bolt keeps track of the state independently for each set;
+the student may begin refresh for set A while
+partway through refresh for set B.
 
 === Changing course documents ===
@@ -268 +415 @@
 they share a single state.
 
-== Control structures ==
-=== Sequences ===
-
-Sequences were described above.
-
-=== 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 unit for which this value is greatest is shown.
-The value function may be partly or entirely random.
-
-This structure can be used to implement
- * "experiments" where different lessons are compared;
- * "adaptive courses" where different lessons are shown to different types of students.
-or a mixture of the two.
-
-{{{
-<?php
-function value($student, $unit) {
-    return abs($student->verbal_level - $unit->verbal_level);
-}
-
-return select(
-    name('course'),
-    valuator('value'),
-    lesson(
-        name('lesson 1'),
-        filename('bolt_sample_lesson1.php')
-    ),
-    lesson(
-        name('lesson 2'),
-        filename('bolt_sample_lesson2.php')
-    ),
-);
-?>
-}}}
-
-
-=== Random ===
-
-The '''random''' control structure selects randomly (without replacement) from a set of units.
-{{{
-<?php
-return 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')
-    ),
-);
-?>
-}}}
-
-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
-(e.g. because of review or refresh).
-
-=== 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 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.
-
-Example:
-{{{
-exercise_set(
-    name('exer_set'),
-    number(1),
-    exercise(
-        name('exercise 1'),
-        filename('file_1.php')
-    ),
-    exercise(
-        name('exercise 1'),
-        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 ==
-
-The "repeat" items in an exercise set determine the student's options
-to review for and repeat the exercise set.
-(
-Each repeat item is a function call of the form
-{{{
-repeat(grade_threshold, review_unit, nav_flags);
-}}}
-The arguments are:
- * grade_threshold: the highest grade to which this item applies
- * review_unit: a unit that reviews the material assessed by for the exercise set.
- * nav_flags: a bitmask determining which navigation options will be presented:
-  * REVIEW: show the review units, then repeat the exercise set
-  * REPEAT: repeat exercise set immediately
-  * NEXT: continue without repeating the exercise set
-
-A student's score on an exercise set is the average score of the selected exercises.
-Call this Y;
-the "selected repeat item" is the one with the least X such that Y < X.
-
-If there is no such repeat item, the student is not given an option
-to repeat the exercise set; i.e., they see only a Next button.
-
-Otherwise let R be the selected repeat item.
-If R.repeat_optional is true, a Next button is shown.
-If R.review_optional is true, a "Repeat" button is shown.
-If R.review_unit is present, a "Review" button is shown.
-
-Thus, in the example above, the student's options are:
-
-|| grade || options ||
-|| [0, .3) || review and repeat exercise ||
-|| [.3, .7) || review and repeat exercise, or repeat exercise ||
-|| [.7, 1) || repeat exercise, or continue ||
-|| 1 || continue ||
-
-== Memory refresh ==
-
-If a '''refresh()''' argument is given to exercise_set(),
-then when the set is completed by a student it is added to
-a "refresh schedule".
-Each element in a refresh schedule specifies
-The intervals (in days) are given as arguments to refresh().
-
-At a given point, one or more exercise sets may be due for refresh.
-The student may choose any of them to view.
-Bolt keeps track of the state independently for each set;
-the student may begin refresh for set A while
-partway through refresh for set B.
+