[Stack-cvs] stack-1-0/doc en_doc.php,1.2,1.3 stackcvs.png,1.2,1.3

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/stack/stack-1-0/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv21989/doc

Added Files:
	en_doc.php stackcvs.png 
Log Message:
Major changes to the font end.  Attempt 2.

--- NEW FILE: stackcvs.png ---
(This appears to be a binary file; contents omitted.)

--- NEW FILE: en_doc.php ---
<?php
/** 
* Describes the data structure stackQuestion
*
* @package documentation
* @subpackage Stack
*/

$stackQuestion['questionVarsRaw']['doc']="This field is a string which contains a list of assignments 
of the form 
 <tt> key = value </tt> 
 where each <tt>key</tt> is the name of a variable local to the question, and <tt>value</tt>
 is an expression in Maxima's language. When a question is instantiated, this list is
 passed to the CAS, and evaluated in order. The value obtained for
 each <tt>key</tt> will be stored and used later, for example in the
 question marking routines. The keys need not be unique, although only the last
 value will be available for use later.

Maxima's assignments <tt>a:3</tt> 
 Computer algebra systems each use a different syntax to denote the assignment of a value to
 a variable. For example, Maple and Derive use <tt>:=</tt>. Mathematica uses 
 <tt>=</tt> or <tt>:=</tt>, depending on when the assignment is to take place. Maxima uses
 the form <tt>key:value</tt>, which is unusual and not intuitive. 
 Maxima reserves <tt>:=</tt> to denote function definition, eg <tt>f(x):=x^2</tt>.
 Hence, in STACK we add an abstraction layer to enforce a syntax where 
 every expression must be of the form <tt> key = value </tt>.

  <p>Examples are included in the authoring guide.</p>

Notes
 <ul>
 <li>Items are separated by either a newline or ;</li>
 <li>If you type a string not in the form <tt> key = value</tt>, a variable name such as <tt>dumvar3</tt>
 will be assigned automatically to keep track of the command in the list of question variables.</li>
 <li>These raw values are internalized as a PHP array, in this case stored in <tt>questionVars</tt>.
 Hence, the field may change when you edit the question.</li>
 <li>If a student uses a variable which has been assigned a value, the value will be used instead during
 the marking procedure. Hence, if you ask the student for an expression such as 
 <tt>x^2-n</tt> in a question, it would be better not to use <tt>n</tt> here in case
 a student literally types this expression. 
 </ul>";

$stackQuestion['questionVars']['doc']="This field is an array which holds the actual parsed 
values of the text given in the field
<tt>questionVarsRaw</tt>.
Internally in PHP this is stored as a numbered array, each entry of
which is of the form <tt>array('key' => \$var_name, 'value' => \$value)</tt>.";

$stackQuestion['questionStem']['doc']="This is the string, ie the question, which the
student actually sees. This is of the nominal data type <tt>castext</tt>, so that
it may depend on the <tt>questionVars</tt>. The student will of course see the instantiated versions.";

$stackQuestion['questionAns']['doc']="Each question must have a non-empty answer, whether or not this is
 actually used by the various marking schemes. This answer must be a
 CAS specific string, ie. it is assumed to be of type <tt>casstring</tt>. 
 If you want the answer to be a string, use quotes, for example <tt>\"hello world\"</tt>";

$stackQuestion['questionAnsKey']['doc']="If there are any <tt>questionPotResp</tt> in the question, 
which is to say a list
 of potential responses. This field will be used. When generating feedback to a question, 
 based upon the student's answer, we have to refer to the student's answer using a variable
 name. This field allows such a local variable name to be set. All
 fields of the <tt>questionPotResp</tt> and the <tt>questionAnsVars</tt>
 may refer to this. The <tt>questionSol</tt>, that is the worked
 solution, may not refer to the student's answer. This field is required, and a default value is assigned
 to a blank question. This will only appear when potential responses are added.";

$stackQuestion['questionAnsVarsRaw']['doc']="This field is treated in exactly the same way as the <tt>questionVarsRaw</tt> field above. When a student has responded to a question, this list of variables will be processed. They may depend on
 <ol>
 <li> The <tt>questionVarsInst</tt>, that is to say the instantiated question variables.</li>
 <li> The <tt>questionAnsKey</tt>, so that feedback may be given in terms of the student's answer.</li>
 </ol>";

$stackQuestion['questionAnsVars']['doc']="See <tt>questionVars</tt>.";

$stackQuestion['questionPotResp']['doc']="This is an array of potential responses, each of type <tt>stackQuestionPotResp</tt>. See the specific documentation about this.";

$stackQuestion['questionSol']['doc']="This castext is only displayed when the student asks to see the worked solution to a question. Note: the Worked solution may not depend on the <tt>questionAnsVars</tt> field";

$stackQuestion['questionOptions']['doc']="These are the options for the question.  Only some will be set specifically at the question level, and these will be
 stored in this array.  See the specific documentation on each option.";

$stackQuestion['questionNote']['doc']="This allows a teacher to leave an intelligent 
\"note to self\" about which 
 instances of variables a student has been given.  The whole list of variables can be inspected, but 
 some will only be intermediates.  This is useful for giving the student a hint, or for analysis of 
 incorrect answers.";

$stackQuestion['questionID']['doc']="This is a unique system identifer for the question, in the database.";

$stackQuestion['questionGUID']['doc']="This is a globally unique identifer for the question.";

$stackQuestion['questionName']['doc']="The name of the question.";

$stackQuestion['questionDescription']['doc']="The description the question.";

$stackQuestion['questionKeywords']['doc']="Keywords, for searching over banks of questions.  Note that any question with the keyword 'demo' will appear as a demo question for guest users and students to try and edit.";

$stackQuestion['questionBody']['doc']="This field stores the serialized body of the question in the database.";

$stackQuestion['questionUserLastEdited']['doc']="Shows who edited the question last.";

$stackQuestion['questionDateLastEdited']['doc']="An automatic time stamp showing when the question was last edited.";

// three extra fields!

$stackQuestionInst['questionInstAttempts']['doc'] = "This holds the student's attempts at this question, in an array of <font color=\"orange\"><tt>stackQuestionAttempt</tt></font>.";

$stackQuestionInst['questionSeedInst']['doc']      = "This holds a random number used to generate the
questionInst.  This is a combination of clock time and user number";

$stackQuestionInst['questionAnsTestOptInst']['doc'] = "If the AnswerTest is of type 'cas', then any non-empty AnsTestOpt needs to be instantiated.  This field stores the result of this,
making it available to the response processing part";

////////////////////////////////////
// Potential Responses 
////////////////////////////////////

$stackQuestionPotResp['SAns']['doc']="This is a CAS expression which we consider nominally to be the response of the student.
The default value of this is the field <tt>questionAnsKey</tt>. 
The AnswerTest will be applied with this against the value in <tt>TAns</tt>.";

$stackQuestionPotResp['TAns']['doc']="This is a CAS expression which we consider nominally to be the 
response of the teacher. Of course, it could be the answer or a common mistake.
The default value of this is the field <tt>questionAns</tt>.
 The AnswerTest will be applied with this against the value in <tt>SAns</tt>.";

$stackQuestionPotResp['AnsTest']['doc']="The AnswerTest to be applied to this response.";

$stackQuestionPotResp['AnsTestOpt']['doc']="The AnswerTest Options, for this AnswerTest.";

$stackQuestionPotResp['RawMarkMod']['doc']="The way in which the <tt>RawMark</tt> for this branch of the potential response is used to affect the RawMark for the attempt as a whole. It must be one of the values, =, +, - or =AT. The latter assigns the mark to be that returned by the AnswerTest, in the case where partial credit is returned.";

$stackQuestionPotResp['RawMark']['doc']="The mark applied for this attempt, should be between 0 and 1, although does not need to be.";

$stackQuestionPotResp['Penalty']['doc']="The penalty applied for this attempt, if this branch is activated.  The last such modified penalty is used.  If nothing is set, then the normal penalty scheme for the question as a whole is used.   This value should be either (i) between 0 and 1, (although does not need to be), or (ii) the string '' or 'default'.  Basically this is a way to make sure a specific penalty is set, regardless of the mark.  Useful for removing a penalty in the case of a common and silly slip.";

$stackQuestionPotResp['FeedBack']['doc']="This castext is only generated if this branch of the distracter is activated. The context in which this is evaluated is as follows:
 <ol>
 <li> <tt>questionVarsInst</tt> </li>
 <li> <tt>questionAnsInst</tt>, using the name given by <tt>questionAnsKey</tt> </li>
 <li> <tt>questionAnsVarsInst</tt> </li> </ol>
 This castext is then concatenated to form the FeedBack for this attempt.";

$stackQuestionPotResp['AnswerNote']['doc']="This string is added to the AnswerNote for the attempt at this question.";

$stackQuestionPotResp['ApLat']['doc']="This literally asks \"Apply which later test?\". It must be the number of an
 existing potential response. This will allow branching and the construction of tree like flow charts
 for the execution of feedback or partial credit. There are two provisos: <ul><li> No potential response is executed
 more than once. If this happens, the marking scheme bails out and takes no further action. This
 is to prevent loops.</li> <li> If the value of this field does not correspond to a legitimate
 Potential response, then the marking scheme bails out and takes no further action.</li></ul> This latter
 can be used to advantage by assigning the field a value of -1 to indicate the end of the process.
 The default blank potential responses do not jump, but finish the process.";

////////////////////////////////////
// Options 
////////////////////////////////////

   // descript = The string which is displayed on screen
   // type     = string,  free string value
   //          = html,    HTML text
   //          = email,   email address (validates)
   //          = url,     URL (validates)
   //          = list, 
   //          = number,
   // values   = possible values, for a list this is an array.
   // default  = default value.  There must be one!

$stackOptions['InsertStars']['doc']="If set to TRUE, the system will automatically insert *'s into a student's answer, (actually any casstring) when it is validated. So, for example <tt>2(1-4x)</tt> will be changed to <tt>2*(1-4*x)</tt>.";

$stackOptions['InformalSyntax']['doc']="If set to TRUE, the system will automatically insert *'s into a student's answer, (actually any casstring) and it will not throw an error. Note
however, that this is actually very hard to define robustly, since <tt> x(x+1) </tt> means apply the function <tt>x</tt> to the argument </tt>(x+1)</tt>, whereas <tt>sin(x)</tt> would be fine. How does one distinguish between the two? The system currently assumes a single letter is a variable, and otherwise this is a function to be applied. So <tt> tx(x-1) </tt> will not mean <tt> t*x*(x-1)</tt>";

$stackOptions['AllowInputTool']['doc']="The default is just to have a form box
for the student's entry. If set to 'Form box + JOME, the system will allow the use of the 
JOME mathematical input tool, to help student enter their answers. 
There are a variety of such tools, and others could easily be substituted, although it 
is likely an implementation needs only one. Furthermore, there will need to be 
javascript in the page, and so on. 
Hence, the file <tt>inputtool.inc</tt> and the function <tt>stack_question_inst_try_formfrag</tt> 
allow this to be integrated into the system. 
More than one input tool per implementation is not supported.";

$stackOptions['SyntaxHint']['doc']="A syntax hint allows the teacher to
give the student a pro-forma in the input box. This can include '?' characters
(which the CAS treats as the special variable <tt>qmchar</tt>). 
The syntax hint will appear in the answer box, whenever this is left blank by the student.
For example, rather than having to type
<pre>matrix([1,2],[3,4])</pre>
the teacher may want to provide an answer box which already contains the string
<pre>matrix([?,?],[?,?])</pre>
instead. The student then need only to edit this, to replace ?'s with their values.
This helps reduce syntax error problems with more difficult syntax issues.
The ? may also be used to give partial credit.
Of course it could also be used for general expressions such as
<pre>x^2+?*x+1</pre>
";

$stackOptions['Display']['doc']="This determines how strings are displayed
 by the system. The <tt>String</tt> representation is exactly the
 CAS string. LaTeX uses the CAS's tex() function, and then passes
 the result through TTH. MathML is not implemented in all CAS
 systems. The \"LaTeX Source\" option generates LaTeX code, but does
 not process it. This can be cut and pasted into other LaTeX documents.";

$stackOptions['Language']['doc']="This determines the language used for STACK.";

$stackOptions['QuVal']['doc']="This is the number of marks available for the question.";

$stackOptions['MarkModMethod']['doc']="This allows the teacher to specify how different marks for repeated attempts at this question are treated.
The mark modification method is a function which applies to the list of raw marks, and returns a mark for this attempt. 
There are two mark modification methods.
<ul>
<li>Penalty 
This is the default method, which has been tried for many years using the AiM system.
For each incorrect attempt, which is valid and the student asks to be marked, a penalty is accumulated. 
The AttemptMark is the AccumulatedPenalty for that attempt, subtracted from the RawMark. 
The mark for this attempt is the maximum AttemptMark. Thus a mark cannot 'go down'. This prevents a student for being penalized for
continuing to try to gain credit. 
</li>
<li>Last Answer 
This is the RawMark for this attempt, and disregards all penalties and previous answers. Note, this is different
from setting the penalty to be zero, and using the penalty scheme above. With this method if a student leaves
an incorrect answer in place they will not be given credit for any previous correct attempt.
</li>
</ul>";

$stackOptions['Penalty']['doc']="This is the penalty applied to each different incorrect attempt, which is valid, and which the student has asked to be marked.  This is subtracted from the basic question value of 1, and so must lie within the range 0 to 1, to make any sense.";

$stackOptions['Forbid']['doc']="This is a comma separated list of text
 strings which are forbidden in a student's answer. If one of these
 strings is present then the student's attempt will be considered
 invalid, and no penalties will be given. The Forbid option works in
 a slightly different way from other options. The \"default\" values
 are added to the options entered at the question level, not
 over-written. So to forbid <tt>diff</tt> for a whole quiz, just set
 it at the quiz level. And so on. To allow a word forbidden at a
 higher level, use Allow.";

$stackOptions['Allow']['doc']="See Forbid above.";

$stackOptions['AnsTest']['doc']="This determines which answer test will be
  applied to the pair consisting of the student's and teacher's answers.  See the specific documentation.";

$stackOptions['AnsTestOpt']['doc']="This allows an option to be passed to
 the <tt>AnswerTest</tt>. Not all <tt>AnswerTest</tt>'s require one. See the specific documentation. This option is considered to be a CASString, and so if non-empty must be a valid CASString.";

$stackOptions['TeacherEmail']['doc']="This is the email address that appears on the page for students
to email help";

$stackOptions['FeedBackGenericCorrect']['doc']="This is the string displayed to the student when their answer gets full marks, in addition to anything from the response processing tree or answer tests.";
$stackOptions['FeedBackGenericIncorrect']['doc']="This is the string displayed to the student when their answer gets full marks, in addition to anything from the response processing tree or answer tests.";
$stackOptions['FeedBackGenericPCorrect']['doc']="This is the string displayed to the student when their answer gets full marks, in addition to anything from the response processing tree or answer tests.";
$stackOptions['ShowSol']['doc']="This determines when any worked solution is available.";

////////////////////////////////////
// Answer tests
////////////////////////////////////

$stackAnswerTest['AlgEquiv']['doc']="This is full algebraic simplification, as
 far as is possible within the computer algebra system. This is a
 basic test, available to all CAS systems, and is the default
 test. In essence we take <tt>StudentAnswer-TeacherAnswer</tt> and
 shake it around in as many ways as possible. If the result is zero
 we return true.";

$stackAnswerTest['CASEqual']['doc']="This is test if the CAS returns TRUE
 when asked to evaluate <tt>StudentAnswer=TeacherAnswer</tt> as a Boolean.
 There is no explicit simplification here (unlike AlgEquiv) and so this is
 very much at the mercy of the CAS system being used.";

$stackAnswerTest['Num_tol_relative']['doc']="This is test checks to 
see if the difference between the teacher's answer (ta) and student's answer (sa)
is within a tolerance of the answer. The default tolerance is 5%, but this can
be changed with the answer test option. Literally this test is passed if
<center> <tt>abs(sa-ta) <= tol * abs(ta)</tt> </center>
and false otherwise.";

$stackAnswerTest['Num_tol_absolute']['doc']="This is test checks to 
see if the difference between the teacher's answer (ta) and student's answer (sa)
is within a tolerance of the answer. The default tolerance is 0.05, but this can
be changed with the answer test option. Literally this test is passed if
<center> abs(sa-ta) <= tol</center>
and false otherwise.";

$stackAnswerTest['String']['doc']="This is a string match, ignoring leading and
  trailing white space which are stripped from all answers, using PHP's <tt>trim()</tt> function.";

$stackAnswerTest['StringSloppy']['doc']="This function first converts both
  inputs to lower case, then removes all white space from the string
  and finally performs a strict string comparison.";

$stackAnswerTest['RegExp']['doc']="A regular expression match, with the
 expression passed via the AnsTestOpt option. This regular
 expression match is performed with PHP's <a href=\"http://uk2.php.net/manual/en/function.ereg.php\"><tt>ereg()</tt></a> function.
 For example, if you want to test if a string looks like a floating point number then use the regular expression
 <pre>[0-9]*\.[0-9]*</pre>";

$stackAnswerTest['FacForm']['doc']="This test essentially checks (i) that <tt>SAns</tt> is algebraically
equivalent to <tt>TAns</tt>, and (ii) that <tt>SAns</tt> is \"factored\". The answer test 
expects the first argument to be the student's answer, the second 
to the teachers answer and the AnswerTest options to be the 
variable. If the answer is incorrect, quite detailed feedback is provided. 
See the AnswerTest <tt>SA_factored</tt> for more details.";

$stackAnswerTest['SA_factored']['doc']="This test checks to see if the expression
in <tt>SAns</tt> is considered to be \"factored\". It shares code as the AnswerTest <tt>FacForm</tt>, 
so that the two tests should agree. However it provides no feedback and any <tt>TAns</tt> is ignored. It
still needs the variable as an AnswerTest option. 
 This test is similar but slightly different from the command <tt>factorp(ex)</tt>, 
which is defined as part of the STACK code, not the Maxima distribution.
This test is somewhat at the mercy of what the CAS is able to 
factor, and exactly what it factors. Hence these two tests which are more careful.
First, we have that (3-x) is considered to be a factored expression, even though in 
Maxima, <tt>factor(3-x)=-(x-3)</tt>. Secondly, a linear term in variable, with a coefficient
in of the variable 1, is always considered to be factored. This covers cases such as 3(x-1/3).
There are other cases, which can be spotted in the test suite by looking for 
Answer Notes \"correct by default\".";

$stackAnswerTest['SA_expanded']['doc']="This test checks to see if the expression
in <tt>SAns</tt> is considered to be expanded. 
 This test is implemented with the command <tt>expandp(SA)</tt>, 
which is defined as part of the STACK code, not the Maxima distribution.
Literally in Maxima, is <tt>expand(SA)=SA</tt>?";

$stackAnswerTest['Diff']['doc']="This test is a general differentiation test.
The first argument is the student's answer. The answer test options needs to be the variable.";

$stackAnswerTest['Int']['doc']="This test is a general integration test.
The first argument is the student's answer.  The second answer 
should be the teachers answer, for use when this answer test is used as 
a stand alone test.  The answer test options needs to be the variable.";

$stackAnswerTest['SA_True']['doc']="This gives access to the CAS's Boolean functions.  This sends the expression in SA to the CAS, and ignores TA.   If the result of the evaluation is the string 'true' (case insensitive, ignoring white space) the result of the test is TRUE, otherwise FALSE.";

$stackAnswerTest['True']['doc']="This is a catch-all AnswerTest which always evaluates to true.  This is useful when providing feedback at the end of a list of potential responses.";

?>