Changes between Version 39 and Version 40 of BoltRef

Timestamp:

Oct 24, 2008, 4:47:38 PM (16 years ago)

Author:

davea

Comment:

--

BoltRef

@@ -137 +137 @@
 }}}
  '''title''' :: a name shown to students 
+
+'''NOTE: the parameters of lesson() and all other course document API functions
+can be given in any order.'''
 
 === Exercise ===
@@ -338 +341 @@
 partway through refresh for set B.
 
-== Changing course documents ==
-
-Course documents can change over time.
-In fact, that's the whole point of Bolt:
-to constantly study the effectiveness of course materials,
-and change the course based on the results of that study.
-
-If a course changes while students are in the middle of it,
-Bolt recovers as gracefully as possible.
-For each student, Bolt maintains a "course state" - a set of data,
-for each control structure that the student has visited in the course,
-describing the student's "position" in that control structure.
-When a student clicks the Next button, or resumes the course after an interval,
-Bolt uses the course state to decide what item to display next.
-
-For example, suppose your course has a sequence with 3 elements,
-with logical names (red, yellow, blue).
-and a student is on the third.
-The course state for the sequence consists of two items: (blue, 2).
-'blue' is the logical name of the third element, and the index number 2
-(indicates that the student has completed 2 units in the sequence).
-
-If the student resumes the course, Bolt will find their place in
-the sequence first by looking up the logical name;
-if it is not found, then it will use the index number.
-For example:
- * If you change the sequence to (red, blue, green, yellow) then the student will be shown the units blue, green, and yellow.
- * If you change the sequence to (red, yellow, green) then the student will be shown the unit 'green'.
- * If you change the sequence to (red, yellow) then the student will have finished the sequence.
-
 === Nesting and functions ===
 
@@ -402 +375 @@
 }}} 
 
+=== Course document notation explained ===
+
+If you're familiar with PHP you may wonder how Bolt's notation works.
+The answer is that it uses get_func_args() and PHP's ability to
+identify variable types at runtime.
+There's a PHP class hierarchy underlying it;
+units are represented by classes like BoltExercise, BoltSequence, etc.,
+all of which are derived from BoltUnit.
+So
+{{{
+sequence(
+    name("foo"),
+    lesson(filename("blah.php"))
+);
+}}}
+is equivalent to
+{{{
+new BoltSequence(
+   "foo",
+   array(new BoltLesson("blah.php"))
+);
+}}}
+== Changing course documents ==
+
+Course documents can change over time.
+In fact, that's the whole point of Bolt:
+to constantly study the effectiveness of course materials,
+and change the course based on the results of that study.
+
+If a course changes while students are in the middle of it,
+Bolt recovers as gracefully as possible.
+For each student, Bolt maintains a "course state" - a set of data,
+for each control structure that the student has visited in the course,
+describing the student's "position" in that control structure.
+When a student clicks the Next button, or resumes the course after an interval,
+Bolt uses the course state to decide what item to display next.
+
+For example, suppose your course has a sequence with 3 elements,
+with logical names (red, yellow, blue).
+and a student is on the third.
+The course state for the sequence consists of two items: (blue, 2).
+'blue' is the logical name of the third element, and the index number 2
+(indicates that the student has completed 2 units in the sequence).
+
+If the student resumes the course, Bolt will find their place in
+the sequence first by looking up the logical name;
+if it is not found, then it will use the index number.
+For example:
+ * If you change the sequence to (red, blue, green, yellow) then the student will be shown the units blue, green, and yellow.
+ * If you change the sequence to (red, yellow, green) then the student will be shown the unit 'green'.
+ * If you change the sequence to (red, yellow) then the student will have finished the sequence.
+
+
+
 === Logical names and state ===