|
From: <nps...@us...> - 2003-07-10 20:10:08
|
Update of /cvsroot/aimmath/AIM/doc
In directory sc8-pr-cvs1:/tmp/cvs-serv8131/doc
Modified Files:
Tag: develop_2_1
format.html todo.html
Log Message:
Many changes, mostly to implement multipart questions
Index: format.html
===================================================================
RCS file: /cvsroot/aimmath/AIM/doc/format.html,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.2.1
diff -C2 -d -r1.1.1.1 -r1.1.1.1.2.1
*** format.html 20 Apr 2003 23:14:41 -0000 1.1.1.1
--- format.html 10 Jul 2003 20:10:05 -0000 1.1.1.1.2.1
***************
*** 68,71 ****
--- 68,72 ----
<pre><font color='green'>
+ shift> 87453978
local> p,x
h> p := x^4 + randpoly(x, degree=3, coeffs=rand(-3..3));
***************
*** 87,90 ****
--- 88,99 ----
<br>
<ul>
+ <li>It is recommended that every question should have a
+ <tt><font color='green'>shift></font></tt> flag, whose argument is
+ a randomly chosen integer, which should be left unchanged when
+ the question is edited. The reason for this is technical: it
+ ensures that questions are robustly randomized, while minimizing
+ the damage if a question needs to be modified while a quiz is
+ running.
+ </li>
<li>The <tt><font color='green'>local></font></tt> flag says that p
and x are local variables for this question. Without this, if x had
***************
*** 94,99 ****
is processed, and the value assigned to p is removed afterwards.
AIM is reasonably good at working out which variables should be
! treated as local, but it is nonetheless good practise to tell it
explicitly.
</li>
<li>The <tt><font color='green'>h></font></tt> (hidden) flag
--- 103,113 ----
is processed, and the value assigned to p is removed afterwards.
AIM is reasonably good at working out which variables should be
! treated as local, but it is nonetheless good practice to tell it
explicitly.
+
+ We refer to variables declared in this way as
+ <em>pseudolocals</em>. As far as Maple is concerned, they are
+ actually global variables, but AIM itself sets and unsets them at
+ appropriate points to make them behave locally.
</li>
<li>The <tt><font color='green'>h></font></tt> (hidden) flag
***************
*** 113,118 ****
plain text, not LaTeX). If the <tt><font
color='green'>note></font></tt> flag is omitted, then AIM will
! construct a note recording the values of all local variables; for
! more elaborate questions, this can be awkward and inefficient.
</li>
<li>
--- 127,132 ----
plain text, not LaTeX). If the <tt><font
color='green'>note></font></tt> flag is omitted, then AIM will
! construct a note recording the values of all pseudolocal variables;
! for more elaborate questions, this can be awkward and inefficient.
</li>
<li>
***************
*** 131,135 ****
\[ @Int(p,x)@ \]
</font></pre>
! (using the neutral integration operator Int).
</li>
<li>
--- 145,154 ----
\[ @Int(p,x)@ \]
</font></pre>
! (using the neutral integration operator Int). Expressions in this
! context can only refer to global and pseudolocal variables, not to
! local variables or parameters. This is not in practice a
! restriction for <tt><font color='green'>t></font></tt> flags, but
! it will be a restriction in various other contexts discussed later
! where the same syntax is used.
</li>
<li>
***************
*** 165,168 ****
--- 184,188 ----
<pre><font color='green'>
+ shift> 8748273605
t> The following figure
p> plots[display](plottools[torus]([0,0,0],1,2), scaling=constrained);
***************
*** 210,218 ****
<pre><font color='green'>
# A multiple-response question.
t> Consider the following matrix:
p> A = matrix(2, 2,
[cos(theta),-sin(theta),
sin(theta), cos(theta)]);
! t> Which of the following properties does this matrix posess?
c> MR("symmetric", "anti-symmetric", "orthonormal", "singular", "non-singular")
a> {"orthonormal", "non-singular"}
--- 230,239 ----
<pre><font color='green'>
# A multiple-response question.
+ shift> 9066875006
t> Consider the following matrix:
p> A = matrix(2, 2,
[cos(theta),-sin(theta),
sin(theta), cos(theta)]);
! t> Which of the following properties does this matrix possess?
c> MR("symmetric", "anti-symmetric", "orthonormal", "singular", "non-singular")
a> {"orthonormal", "non-singular"}
***************
*** 227,230 ****
--- 248,341 ----
worse, and 1 for a perfectly correct answer.
+ <h3>A question with several parts</h3>
+
+ A question may be divided into subquestions (which may in turn be
+ further subdivided). This is only recommended when the subquestions
+ are linked, so that the mark for one part might depend on the
+ answer given to another part. Here is an example:
+
+ <pre><font color='green'>
+ name> primes
+ local> lowerbound,ans1
+ shift> 7645848653
+ t> Recall that Euclid proved that their are infinitely many primes
+ h> lowerbound := rnd(20..40);
+ note> sprintf("p2>p1>%a",lowerbound)
+ sq>
+ t> Find a prime $p_1$ such that $p_1 > @lowerbound@$
+ c> posint
+ av> p1
+ ap> $p_1 =$
+ s> [proc(ans)
+ if isprime(ans) then
+ if ans > lowerbound then
+ RETURN(1);
+ else
+ `aim/t`("Your answer is prime, but is too small.");
+ `aim/SetAnswerNote`("too small");
+ fi;
+ else
+ ans1 := ans;
+ `aim/t`("Your answer is composite: $@ans1@ = @ifactor(ans1)@$");
+ `aim/SetAnswerNote`("composite");
+ fi;
+ RETURN(0);
+ end,
+ nextprime(lowerbound)
+ ]
+ esq>
+ sq>
+ t> Find a another prime $p_2$ such that $p_2 > p_1$
+ c> posint
+ av> p2
+ ap> $p_2 =$
+ s> [proc(ans)
+ if isprime(ans) then
+ if ans > p1 then
+ RETURN(1);
+ else
+ `aim/t`("Your answer is prime, but is too small.");
+ `aim/SetAnswerNote`("too small");
+ fi;
+ else
+ ans1 := ans;
+ `aim/t`("Your answer is composite: $@ans1@ = @ifactor(ans1)@$");
+ `aim/SetAnswerNote`("composite");
+ fi;
+ RETURN(0);
+ end,
+ nextprime(nextprime(lowerbound))
+ ]
+ esq>
+ end>
+ </font></pre>
+
+ The subquestions are enclosed between <tt><font
+ color='green'>sq></font></tt> and <tt><font
+ color='green'>esq></font></tt>. The <tt><font
+ color='green'>c></font></tt> flags specify that the answers should
+ have the maple type <tt><font color='green'>posint</font></tt>, in
+ other words they must be positive integers. If not, then the answers
+ are rejected as being invalid, without any penalty. The line
+ <tt><font color='green'>av> p1</font></tt> specifies that at an
+ appropriate point, the global variable <tt><font
+ color='green'>p1</font></tt> should be set equal to the student's
+ first answer; this allows the second marking procedure to refer to
+ <tt><font color='green'>p1</font></tt> when it checks that
+ p<sub>2</sub> > p<sub>1</sub>. (This assignment is automatically
+ removed when it is no longer needed.) The <tt><font
+ color='green'>ap></font></tt> flag specifies the string used to prompt
+ the student for an answer. The
+ <tt><font color='green'>`aim/t`</font></tt> function works like a
+ <tt><font color='green'>t></font></tt> flag; see
+ <a href='#hide'>below</a> for more details. One subtlety is that
+ <tt><font color='green'>@...@</font></tt> sequences in the argument
+ to <tt><font color='green'>`aim/t`</font></tt> only work with
+ global or pseudolocal variables, hence the need to copy the parameter
+ <tt><font color='green'>ans</font></tt> to the pseudolocal variable
+ <tt><font color='green'>ans1</font></tt>. Note also the use of the
+ <tt><font color='green'>`aim/SetAnswerNote`</font></tt> function to
+ record a short note about the general nature of the answer; this is
+ used by AIM's facilities for analyzing results.
<h2>Detailed description of flags</h2>
***************
*** 240,244 ****
<tr><td>ap></td>
<td><a href='#prompt'>prompt></a></td>
! <td>Specify the prompt for the student's answer</td>
</tr>
<tr><td>c></td>
--- 351,361 ----
<tr><td>ap></td>
<td><a href='#prompt'>prompt></a></td>
! <td>Specify the prompt for the student's answer (in LaTeX)</td>
! </tr>
! <tr><td>pp></td>
! <td><a href='#prompt'>postprompt></a></td>
! <td>Specify a string to go directly after the box in which the
! student's answer is entered.
! </td>
</tr>
<tr><td>c></td>
***************
*** 311,314 ****
--- 428,439 ----
<td>Specify the value of the question</td>
</tr>
+ <tr><td>sq></td>
+ <td><a href='#subquestion'>subquestion></a></td>
+ <td>Declare the start of a subquestion</td>
+ </tr>
+ <tr><td>esq></td>
+ <td><a href='#endsubquestion'>endsubquestion></a></td>
+ <td>Declare the end of a subquestion</td>
+ </tr>
<tr><td><<i>string</i>></td>
<td><a href="#<string>"><<i>string</i>></a></td>
***************
*** 337,340 ****
--- 462,479 ----
</font></pre>
+ <a name='postprompt'><h3>postprompt>/pp></h3></a>
+
+ For example, if the answer is supposed to be a length measured in
+ meters, then one could have a line
+ <pre><font color='green'>
+ postprompt> meters
+ </font></pre>
+
+ <a name='answervariable'><h3>answervariable>/av></h3></a>
+
+ The attached text should be the name of a global variable in which to
+ record the students answer, so that other parts of the same question
+ can refer to it.
+
<a name='mapletype'><h3>mapletype>/c></h3></a>
***************
*** 455,459 ****
functions that can be used in these flags:
<ul>
! <li>The function `aim/t` mimics the behaviour of the <tt><font
color='green'>t></font></tt> flag. The advantage is that it can be
made conditional, for example
--- 594,598 ----
functions that can be used in these flags:
<ul>
! <li>The function `aim/t` mimics the behavior of the <tt><font
color='green'>t></font></tt> flag. The advantage is that it can be
made conditional, for example
***************
*** 477,481 ****
</font></pre>
</li>
! <li>Analogously, the function `aim/p` mimics the behaviour of the
<tt><font color='green'>p></font></tt> flag.
</li>
--- 616,620 ----
</font></pre>
</li>
! <li>Analogously, the function `aim/p` mimics the behavior of the
<tt><font color='green'>p></font></tt> flag.
</li>
***************
*** 628,635 ****
initially had no assigned value, then its unassigned state is also
restored.) This kind of scoping is handled by AIM itself; as far as
! Maple is concerned, the variables in question are global. Some
! technicalities are discussed in the documentation of the <a
! href='Local.html'>Local package</a>, but they can be ignored by most
! users.
<br><br>
Example:
--- 767,774 ----
initially had no assigned value, then its unassigned state is also
restored.) This kind of scoping is handled by AIM itself; as far as
! Maple is concerned, the variables in question are global, so we refer
! to them as <em>pseudolocals</em>. Some technicalities are discussed
! in the documentation of the <a href='Local.html'>Local package</a>,
! but they can be ignored by most users.
<br><br>
Example:
***************
*** 836,845 ****
color='green'>s></font></tt> flag, then the maximum mark is ignored
except that an error will be generated if the checking procedure
! returns a mark that is too large.<h3><a name="<string>"><<i>string</i>>/<<i>string</i>></a></h3>
- This family of flags (one flag for each value of <b><i>string</i></b>) are used
- to define named strings called <i>question parameters</i>. The attached text is substituted for every occurrence
- of the target string (which is exactly the same string as the flag, i.e. <<i><b>string</b></i>>) in the text attached to
- flags that follow this line within the same question.
<p>Example:</p>
<pre><font color="green">#######################
--- 975,1000 ----
color='green'>s></font></tt> flag, then the maximum mark is ignored
except that an error will be generated if the checking procedure
! returns a mark that is too large.
!
! <a name='#subquestion'><h3>subquestion>/sq></h3></a><br>
! <a name='#endsubquestion'><h3>endsubquestion>/esq></h3></a>
!
! These flags should occur in matched pairs to declare subquestions of a
! multi-part question. (For historical reasons,
! <tt><font color='green'>end></font></tt> is allowed as an alternative
! to <tt><font color='green'>esq></font></tt> or
! <tt><font color='green'>endsubquestion></font></tt>.) It is
! recommended that you put all initialization of local variables at the
! beginning, before any subquestions.
!
! <h3><a name="<string>"><<i>string</i>>/<<i>string</i>></a></h3>
!
! This family of flags (one flag for each value of <b><i>string</i></b>)
! are used to define named strings called <i>question
! parameters</i>. The attached text is substituted for every occurrence
! of the target string (which is exactly the same string as the
! flag, i.e. <<i><b>string</b></i>>) in the text attached to flags
! that follow this line within the same question.
<p>Example:</p>
<pre><font color="green">#######################
***************
*** 859,869 ****
# end of foo.aim
######################</font></pre>
! <p>In the first two non-commented lines this example we define two question parameters, <font color="green" face="Courier New" size="2"><Range></font>
! and<font color="green"> <font face="Courier New" size="2" color="green"><Difficulty>.</font></font><font face="Courier New" size="2">
! </font>Every occurrence of <font color="green" face="Courier New" size="2"><Range></font>
! in the subsequent lines is replaced by the string "<font face="Courier New" size="2" color="green">0..9</font>"
! and every occurrence of <font face="Courier New" size="2" color="green"><Difficulty></font>
! in the following lines is replaced by "<font face="Courier New" size="2" color="green">easy</font>".
! After the substitution the question would read:</p>
<pre><font color="green">k> Addition,easy
l> a,b
--- 1014,1032 ----
# end of foo.aim
######################</font></pre>
!
! <p>In the first two non-commented lines this example we define two
! question parameters, <font color="green" face="Courier New"
! size="2"><Range></font> and<font color="green"> <font
! face="Courier New" size="2"
! color="green"><Difficulty>.</font></font><font face="Courier
! New" size="2"> </font>Every occurrence of <font color="green"
! face="Courier New" size="2"><Range></font> in the subsequent
! lines is replaced by the string "<font face="Courier New"
! size="2" color="green">0..9</font>" and every occurrence of <font
! face="Courier New" size="2" color="green"><Difficulty></font> in
! the following lines is replaced by "<font face="Courier New"
! size="2" color="green">easy</font>". After the substitution the
! question would read:</p>
!
<pre><font color="green">k> Addition,easy
l> a,b
***************
*** 874,886 ****
end>
</font></pre>
! <p>Only simple textual substitution is performed - no evaluation of the text
! attached to the flag is performed prior to the substitution. The substitutions
! will only take place on lines that come after the line on which the parameter is
! defined. The targets of the substitutions can occur anywhere in the text
! attached to any flag (but not in a flag itself). In particular, parameter definitions can contain the targets of
! other parameters, but care should be taken to avoid circular substitutions. The
! only exception to this is the include> flag, which cannot contain any
! question parameter targets since all file inclusions are performed before any
! parameter substitution takes place. <br>
<br>
The <b><i>string</i></b>
--- 1037,1053 ----
end>
</font></pre>
!
! <p>Only simple textual substitution is performed - no evaluation of
! the text attached to the flag is performed prior to the
! substitution. The substitutions will only take place on lines that
! come after the line on which the parameter is defined. The
! targets of the substitutions can occur anywhere in the text attached
! to any flag (but not in a flag itself). In particular, parameter
! definitions can contain the targets of other parameters, but care
! should be taken to avoid circular substitutions. The only exception to
! this is the include> flag, which cannot contain any question
! parameter targets since all file inclusions are performed before any
! parameter substitution takes place.
! <br>
<br>
The <b><i>string</i></b>
***************
*** 888,906 ****
contain the character ">" (as that signifies the end of the
flag). Thus, <font face="Courier New" size="2" color="green"><>,</font>
! <font face="Courier New" size="2" color="green"><1>,</font> <font face="Courier New" size="2" color="green"><a>,
<Range></font>,
! and <font face="Courier New" size="2" color="green"><Newton's method number
! of iterations></font> are all valid parameter flags. All occurrences of
! potential targets of the form <<i>string</i>> in the question source code
! for which there is no corresponding parameter defined are left unchanged, so the
! parameter substitution mechanism should have no effect on the ordinary use of
! < and > in a question. The question is compiled after all of the textual
! substitutions of parameters have been made, so no parameter information is stored in the compiled version of
! the question. </p>
! <p>Only the first definition of a particular parameter is used, all subsequent
! definitions of the same parameter within the same question are ignored. This feature is useful for
! making parameterized questions as follows:</p>
--- 1055,1077 ----
contain the character ">" (as that signifies the end of the
flag). Thus, <font face="Courier New" size="2" color="green"><>,</font>
! <font face="Courier New" size="2" color="green"><1>,</font>
! <font face="Courier New" size="2" color="green"><a>,
<Range></font>,
! and <font face="Courier New" size="2" color="green"><Newton's
! method number of iterations></font> are all valid parameter
! flags. All occurrences of potential targets of the form
! <<i>string</i>> in the question source code for which there is
! no corresponding parameter defined are left unchanged, so the
! parameter substitution mechanism should have no effect on the ordinary
! use of < and > in a question. The question is compiled after all
! of the textual substitutions of parameters have been made, so no
! parameter information is stored in the compiled version of the
! question. </p>
! <p>Only the first definition of a particular parameter is used, all
! subsequent definitions of the same parameter within the same question
! are ignored. This feature is useful for making parameterized
! questions as follows:</p>
Index: todo.html
===================================================================
RCS file: /cvsroot/aimmath/AIM/doc/todo.html,v
retrieving revision 1.1.1.1
retrieving revision 1.1.1.1.2.1
diff -C2 -d -r1.1.1.1 -r1.1.1.1.2.1
*** todo.html 20 Apr 2003 23:14:56 -0000 1.1.1.1
--- todo.html 10 Jul 2003 20:10:05 -0000 1.1.1.1.2.1
***************
*** 16,21 ****
<ol>
! <li>Editing of login pages should be moved out of the zone admin
! page to a separate page
</li>
<li>Students should first select a subject, and only then be asked
--- 16,36 ----
<ol>
! <li>Customized parsing procedures eg for permutations, subsets of R, finite
! Abelian groups</li>
! <li>Separate parsing from validation</li>
! <li>Richtext editor option for home pages etc</li>
! <li>Facility for students to request help, with automatic
! recording of the context.
! </li>
! <li>Update error handling to use try/catch/finally</li>
! <li>File locking</li>
! <li>Check whether AIM would load much faster if everything was in
! a single .m file.
! </li>
! <li>Better support for standard question types</li>
! <li>Zone should contain default values for subject options
! (including visibility of newly created subjects).
! Subject should contain default values for quiz options
! (including visibility of newly created quizzes).
</li>
<li>Students should first select a subject, and only then be asked
***************
*** 51,58 ****
<li>Compilation of question files in .mpl or .xml format</li>
<li>Arrange for the server to run as user 'aim', not 'nobody' or 'root'</li>
- <li>Check package dependency statements</li>
- <li>If the student revisits a quiz that they have already tried, we should
- have MarkRequested = true iff that was true at the last visit.</li>
- <li>save times of quiz attempts</li>
<li>Subject-specific and quiz-specific initialization files.</li>
<li>Random package:
--- 66,69 ----
***************
*** 65,75 ****
<li>Check systematically for parsing of strings supplied as CGI parameters,
and ensure safety.</li>
! <li>Internationalize and localize.</li>
! <li>Hints and subquestions</li>
<li>Write HTML help for teachers and include links from admin pages</li>
<li>Multiple choice questions with answers selected from an image map</li>
- <li>Customized parsing procedures eg for permutations, subsets of R, finite
- Abelian groups</li>
- <li>Separate parsing from validation</li>
<li>'Lightweight' question versions with no images or solutions
(used for re-marking, for example)
--- 76,82 ----
<li>Check systematically for parsing of strings supplied as CGI parameters,
and ensure safety.</li>
! <li>Hints</li>
<li>Write HTML help for teachers and include links from admin pages</li>
<li>Multiple choice questions with answers selected from an image map</li>
<li>'Lightweight' question versions with no images or solutions
(used for re-marking, for example)
***************
*** 81,94 ****
<li>In Maple 6: external function calls for file operations and TtH
conversion</li>
- <li>Quiz navigation bar:
- <ol>
- <li>no marks link if marks are not to be reported</li>
- <li>validate, mark, submit buttons?</li>
- <li>return to right position in page</li>
- </ol>
- </li>
- <li>Internationalize collation, conventions about names etc</li>
<li>Date package: better handling of time zones, parallel to Java. Work out
! wht happens while the clocks are changing.</li>
<li>Check treatment of special characters (comma,apostrophe,..) in student
names,id's,passwords, especially when using plain text files</li>
--- 88,93 ----
<li>In Maple 6: external function calls for file operations and TtH
conversion</li>
<li>Date package: better handling of time zones, parallel to Java. Work out
! what happens while the clocks are changing.</li>
<li>Check treatment of special characters (comma,apostrophe,..) in student
names,id's,passwords, especially when using plain text files</li>
***************
*** 113,125 ****
records from the subject review page.
</li>
! <li>Up/download of source directories as zip files
! </li>
! <li>A more systematic way of making toolbars</li>
! </li>
<li>A framework for links to lecture notes.</li>
<li>Hooks for site-specific facilities eg access to central
! records.</li>
! <li>In the Java code, set timouts for TtH and Maple.
! </li>
</ol>
</body>
--- 112,124 ----
records from the subject review page.
</li>
! <li>Up/download of source directories as zip files</li>
<li>A framework for links to lecture notes.</li>
<li>Hooks for site-specific facilities eg access to central
! records.</li>
! <li>Internationalize collation, conventions about names etc</li>
! <li>In the Java code, set timouts for TtH and Maple.</li>
! <li>Check package dependency statements</li>
! <li>save times of quiz attempts</li>
! <li>A more systematic way of making toolbars</li>
</ol>
</body>
|
