[Stack-cvs] stack-1-0/doc about_develop.php,NONE,1.1.2.1 about_general.php,NONE,1.1.2.1 about_instal

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-serv7154/doc

Added Files:
      Tag: frontend_dev
	about_develop.php about_general.php about_install.php 
	author_answertest.php author_commonsyntax.php author_faq.php 
	author_gettingstarted.php author_maxima.php author_options.php 
	author_potresp.php author_questionfields.php 
	student_assessmentmode.php student_forbidden.php 
	student_input.php student_overview.php 
	student_practicemode.php student_understandingoutput.php 
Removed Files:
      Tag: frontend_dev
	Rosetta.pdf aboutSTACK.php author.php develop.php help.html 
	stackAnswerTest.php stackHelp.php stackOptions.php 
	stackQuestion.php stackQuestionPotResp.php testsuite.php 
	todo.php 
Log Message:
Tweaked the menus. 

Moved couple of files into separate directory. 

First sweep at tidying up documentation - note that some of the links previously within pages (using anchors) may need to be removed.

--- stackHelp.php DELETED ---

--- NEW FILE: student_forbidden.php ---

  <a name="forbid"><h2>Forbidden words</h2></a>

Suppose that Stack asked you to calculate
 sin(p/4) (for which the answer is of course
 2-1/2). One cunning plan that might occur to you would
 be to just enter <tt>sin(pi/4)</tt> as your
 answer, leaving the CAS to do all the real work. If this worked, it
 would remove the whole point, so Stack prevents it. For each
 question, there are certain "forbidden words" that you are
 not allowed to use as part of your answer; in the example above, the
 word "sin" would be forbidden. If you give an answer
 involving a forbidden word, Stack will tell you, and you will be
 able to go back and change it without any penalty.

--- NEW FILE: author_faq.php ---
<?php
/** 
* An authoring guide for STACK questions.
*
* @package documentation
* @subpackage Stack
*/

?>

<h1><a name="FAQ">Frequently Asked Questions</a></h1>

<?php

$faqs = array();

$faq['title'] = 'What is LaTeX? Were can I get help learning LaTeX?';
$faq['answer']= 'LaTeX is a document preparation system. For STACK
questions we only need some simple LaTeX, so please do not be
put off. Details about LaTeX are available from
<a href="http://www.latex-project.org/guides/">http://www.latex-project.org/guides/</a>.

Perhaps a better introduction for those totally new to LaTeX is found 
<a href="http://www.comp.leeds.ac.uk/andyr/misc/latex/">here</a> with more 
specific information about 
<a href="http://www.comp.leeds.ac.uk/andyr/misc/latex/latextutorial9.html">mathematics</a>
with examples for you to follow. Note that some of the more complex examples will not work 
on STACK. Just keep things simple.
Another option is <a href="http://www.dessci.com/en/products/texaide/">TeXaide</a>.';

$latexex = array( "x^2", "x_n", "x^{2x}", "\alpha\beta", "\sin(3\pi x)", "\frac{1}{1-n^2}", "\int_a^b x^2\ dx");

$latexstr = '\begin{tabular}{c|c|c}
\LaTeX Fragment, ex & \verb#$ex$# & \verb#\\[ ex \\]# \\\\  '."\n";

foreach ($latexex as $key) {

 $latexstr .= ' \verb# '.$key.' # & $ '.$key.' $ & \\[ '.$key.' \\] \\\\ \hline'."\n";

}
 $latexstr .= '\end{tabular}';
 $latexstr =  stack_latex_to_html($latexstr);

 $faq['answer'] .= "<p>Here are some simple examples</p>$latexstr"; 

$faqs[] = $faq; 

$faq['title'] = 'Can I add HTML to CAS-enabled text?';
$faq['answer']= 'Yes: in your CAS-enabled text, anything contained
between two tags
<tt>&lt html> stuff &lt html></tt> structures is kept as HTML
and not passed through the LaTeX to HTML converter.
You can use these tags to insert references to images etc.';

$faqs[] = $faq; 

$faq['title'] = 'Why does a Maxima function not work in STACK?';
$faq['answer']= 'Not all Maxima functions are enabled by STACK, for obvious security
reasons. You can find a list of which functions STACK will allow on 
<a href="index.php?action=CAS&field=functions">this page</a>. This varies between
different installations of STACK. See the next FAQ entry for more information on how to change
the setting which generate this page.
It may be that your function belongs to a library which
STACK does not load by default. Do you need to use Maxima\'s <tt>load</tt>
command to use it? If so, you will need to ask your system administrator or the
developers to add a <tt>load</tt> command to the file <tt>stackmaxima.mac</tt>
so that this library becomes available.
You should also be aware that there are also a number of functions 
defined by STACK which are not standard Maxima functions. The command
you need may well not be enabled since you should use one STACK provides
instead. Details of these are available <a href="#syntax">here</a>.';

$faqs[] = $faq; 

$faq['title'] = 'How can I change which Maxima functions STACK allows?';
$faq['answer']= 'This is a job for your system administrator, who can 
alter your installation by changing
<pre>
public_html/scripts/maxima/maximafun.php
</pre>
It is not enough to just change this file! 
You will also need to copy and re-run the script
<pre>
$stack_root/scripts/install/install.php
</pre>
as in the install process. This should not re-install the databases
or wipe data, but at the end of the file will generate a number of temporary 
files to reflect your new settings. The most important of these for this purpose is
<pre>
$stack_logfiles/CASkeywords.php
</pre>';

$faqs[] = $faq; 

echo "<ol>";
foreach ($faqs as $key => $faq) {
   echo " <li><a href=\"#fqa{$key}\">{$faq['title']}</a></li>\n";
}
echo "</ol>\n\n";

foreach ($faqs as $key => $faq) {
   $keyno = $key+1;
   echo " <h3><a name=\"fqa{$key}\">{$keyno}. {$faq['title']}</a></h3>\n";
   echo $faq['answer'];
}

?>

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

?>

<h1>Options documentation</h1>

A stackOption is the basic way to affect the system. They are 
an efficient way to transfer information between various parts of 
the code. There is a cascading system of options. Starting with 
the system default values, and options actually set at a lower 
level wil override the current values.

In this way we obtain the maximum flexibility, with the 
maximum consistencey enforced very easily with the minimum of 
fuss. Note, that changing an option at, for example the quiz 
level, will alter the behaviour of all questions at a lower 
level. Hence care needs to be exercised when doing this.

Below are details of all the options. Of course it may make 
no sense to alter options at some levels in the system. The 
option structure simply defines a coherent mechanism for moving 
the information around.

<?php
   foreach( $stackOptions as $field => $q_field) {
       $fd = 'stackOptions_'.$field;
       $fd = get_string($fd,'stack','');
       echo "<h3>$fd</h3>";
       echo $q_field['doc'];
       echo "<p>";
       echo "Name of field: <font color=orange><tt>$field</tt></font>.
       Type of field:  <font color=orange><tt>{$q_field['type']}</tt></font>. ";

       if (is_array($q_field['values'])) {
           echo "Permissable values: <font color=orange><tt>"; 
           show_array($q_field['values']);
           echo "</tt></font>";
       }
       $default = $q_field['default'];
       if ('' == $default) {
         $default = '[none]';
       }
       if ('html' == $q_field['type']) {
           echo 'System default value: <br /><font color=orange><tt>'.htmlspecialchars($default).'</tt></font><br />('.$default.').';
       } else {
           echo "System default value:  <font color=orange><tt>$default</tt></font>.";
       }
   }

?>

--- testsuite.php DELETED ---

--- stackQuestionPotResp.php DELETED ---

--- NEW FILE: author_commonsyntax.php ---
<?php
/** 
* Every CAS system is unique, and they all have different input
* syntaxs.  This file describes some aliases that STACK uses to 
* sort out some of these problems.
*
* @package documentation
* @subpackage Stack
*/

?>

<h1>Common syntax, and STACK commands</h1>

Every CAS system is unique, and they all have different a syntax for doing 
the amazing complex tasks they are asked to perform. 
Each CAS system uses a slightly different syntax,
details of which are given in 
the invaluable <a href="doc/dev/Rosetta.pdf">Rosetta.pdf</a>.
This makes moving from one to the other a difficult task!
Since many CAS systems allow a synonym (or alias) to be set 
up, adapting the function name is not an overwhelming task. 
Furthermore, the vast majority of tasks we need in single variable calculus and 
algebra CAA can be reduced to these tasks. 
So by adopting this common syntax more than expected can be achieved.

This section contains details of basic functions, STACK specific functions
and various ALIAS commands used by STACK to provide users of other CAS systems
a more familiar command name.

<?php

include($stack_root.'/scripts/maxima/stackfun.php');

function disp_cas($type){
    global $stack_cmd;

  echo "<table>\n";
  foreach ($stack_cmd as $fun => $vals) {

      if ($type == $vals['type']) {
      echo "<tr><td nowrap='nowrap' align='top'><b><a NAME=\"STACK_command_$fun\">$fun</a></b></td> 
    <td nowrap='nowrap' align='top'>{$vals['syntax']}</tt></td> 
    <td>{$vals['doc']}</td></tr>\n";
      }
  }
  echo "</table>\n";

}

?>

<h2>Numbers</h2>

<?php disp_cas('num') ?>

<h2>Sets, lists and matrices</h2>

Lists are entered using brackets, eg <tt>[1,2,3]</tt>. These are native to Maxima.
 Sets are implemented using the Maxima package <tt>nset</tt> which is automatically loaded by STACK.
See the <a href="maximadocs/maxdoc/nset.html">specific documentation</a>.
Note that, in addtion to Maxima's use of <tt>set(a1,a2,...,an)</tt>
to construct a set with members a1,a2,...,an, STACK allows the use of
curly braces: <tt>{a1,a2,...,an}.</tt>

 Matrices are a standard part of Maxima, and are entered using a syntax like
<tt>matrix([1,2,3],[x^2,y^2,z^2]);</tt> 
Warning! Maxima uses "." to signify
matrix multiplication, eg <tt>A.B</tt> However, <tt>A*B</tt> is also defined as pointwise
multiplication.

With all these things, if the student needs to enter something as an answer, consider setting the optional
<?php stack_doc_dispstackqfield('SyntaxHint','stackOptions'); ?>

<h2>Trig and "calculator" functions</h2>

Basic "calculator" functions would use their "natural" names.
The angular measure is always assumed to be radians. This is in keeping with the 
CAS, but probably not best suited for more elementary school assessment. Similarly <tt>log</tt> is a natural logarithm.

<table>
<tr> <td> <b>Trig </br> </td> <td><tt>sin(x), cos(x), tan(x)</tt></td> <td> The angular measure is always assumed to be <em>radians</em>.</td> </tr>
<tr> <td> <b>Hyperbolic </br> </td> <td><tt>sinh(x), cosh(x), tanh(x)</tt></td></tr>
<tr> <td> <b>Logarithms </br> </td> <td><tt>log(x), exp(x)</tt></td> <td> Natural logarithms, and exponential function.</td></tr>
</table>

<h2>Algebra</h2>

<?php disp_cas('algebra') ?>

<h2>Calculus</h2>

<?php disp_cas('calculus') ?>

<h2>Random numbers</h2>

<?php disp_cas('rand') ?>

The syntax is as follows. 
<ol>
<li>If <tt>x</tt> is an integer return an integer between 0 and <tt>x-1</tt>.</li>
<li>If <tt>x</tt> is a float return a float in the range 0 to <tt>x</tt>. </li>
<li>If <tt>x</tt> is a list return a randomly selected element.</li>
<li>If <tt>x</tt> is a matrix then rand is applied to every element of this matrix, as above.</li>
</ol>

For the purposes of learning and teaching, we do not need an algorithm which
is statistically perfect. We are much more interested in simplicity, efficiency
and reproducibility across platforms. Hence, we adopt a linear method.

<h2>Plots</h2>

In STACK, the <tt>plot</tt> command has been defined to be a wrapper for Maxima's <tt>plot2d</tt>
command. Try, for example the following.

<pre>@plot(x^2,[x,-1,1])@</pre>

To get many plots in one window, we need to define a list of functions, perhaps with Maxima's 
<a href='maximadocs/maxdoc/maxima_38.html#IDX948'>MAKELIST</a> command.

<pre>@(p(k):=x^k,pl:makelist(p(k),k,1,5),plot(pl,[x,-1,1]))@</pre>

--- aboutSTACK.php DELETED ---

--- NEW FILE: about_general.php ---
<?php
/** 
* A short blurb about what STACK is.
*
* @package documentation
* @subpackage Stack
*/

?>

The STACK system is a sophisticated computer aided assessment 
package for mathematics, which evaluates the student's answer 
using a computer algebra system. Hence the student is required 
to provide their own answer, rather than relying on their 
selection from a teacher-provided list. Using CAS is a natural 
tool for random generation of structured problems, establishing 
mathematical properties of student's answers (eg equivalence with 
a correct answer) and providing feedback.

<p>This system was conceived by <a 
href='email:ch...@sa...'>Chris Sangwin</a>, and is now part 
of the <a href='http://maths.york.ac.uk/serving_maths/'>Serving 
Mathematics in a distributed e-learning environment</a> 
project.</p>

--- Rosetta.pdf DELETED ---

--- NEW FILE: about_develop.php ---
<?php
/** 
* Details of how to Develop.
*
* @package documentation
* @subpackage Stack
*/

?>

<h1>Developing STACK</h1>

This document is intended for people who wish to develop the code for STACK. 
Contributions are welcome, please contact the developers at
<a href="http://sourceforge.net/projects/stack">sourceforge</a> for more information.

<h3>History</h3>

STACK has its roots in the AiM CAA system. The original motivation for the 
project, and core development is by <a href="mailto:ch...@sa...">Chris Sangwin</a>.
If you are using STACK please do contact Chris, as it is always a pleasure
to hear from users.

<table cellpadding='2' border='1'>
<tr><td>Nov 2004-April 2005</td><td>Stack 1.0</td><td>STACK project started as part of the
Serving Mathematics in a Distributed e-Learning Environment project
funded by JISC.</td></tr>
<tr><td>Summer 2004</td><td>Previous work</td><td>Core original code written by 
<a href="mailto:ch...@sa...">Chris Sangwin</a>
and Laura Naismith, at the Centre for Educational Technology and Distance Learning, at the University
of Birmingham</td></tr>
</table>

<h2>Obtaining the STACK code</h2>
STACK code is hosted on <a href="http://sourceforge.net/projects/stack">sourceforge</a>. 
The <a href="http://phpdoc.org/index.php">PHPDoc</a> auto-generated documentation is available
<a href="api/">here</a>.

<h2>Areas in which you can help</h2>

Collaborators of all kinds are welcome to come and help out with this project. 
There are a number of areas in which you can contribute. 
For example:
<UL>
<li>Writing and contributing questions.</li>
<li>Developing the front end - stand alone or in a VLE
<li>Translations to non-English languages</li>
<li>New question types and formats
<li>New answer tests in Maxima's language. 
<li>Documentation and authoring guides.</li>
</ul>

<h2>Coding Guidelines</h2>

These have been copied and adapted from the 
<a href="http://moodle.org/">Moodle</a> coding guidelines and they 
are here to provide a goal for all code to strive to. It's true 
that some code falls short in a few areas, but it will all be 
fixed eventually. All new code definitely must adhere to these 
standards as closely as possible.

<h2>General Rules</h2>
<ol class="normaltext">
  <li class="spaced">All code files should use the .php extension.</li>
  <li class="spaced">All template files should use the .html extension.</li>
  <li class="spaced">All text files should use Unix-style text format (most text 
    editors have this as an option).</li>
  <li class="spaced">All php tags must be 'full' tags like <font color="#339900">&lt;?php 
    ?&gt;</font> ... not 'short' tags like <font color="#339900">&lt;? ?&gt;</font>. 
  </li>
  <li class="spaced">All existing copyright notices must be retained. You can 
    add your own if necessary.</li>
  <li class="spaced">Each file should include the main stackstd.php configuration file.</li>
  <li class="spaced">Each frontend file should check that the user is authenticated correctly.</li>
  <li class="spaced">All variables should be initialised or at least tested for 
    existence using isset() or empty() before they are used.</li>
</li>
</ol>

<h2>Coding Style</h2>
<p>I know it can be a little annoying to change your style 
  if you're used to something else, but balance that annoyance against the annoyance 
  of all the people trying later on to make sense of STACK code with mixed styles. 
  There are obviously many good points for and against any style that people use, 
  but the current style just <strong>is</strong>, so please stick to it. </p>
<ol class="normaltext">
  <li class="spaced"><strong>Indenting</strong> should be consistently 4 spaces. 
    Don't use tabs AT ALL. </li>
  <li class="spaced"><strong>Variable names</strong> should always be easy-to-read, 
    meaningful lowercase English words. If you really need more than one word 
    then run them together, but keep them short as possible. Use
plural names for arrays of objects.
    <p class="examplecode"><font color="#006600">GOOD: $quiz<br />
      GOOD: $errorstring<br />
GOOD: $assignments (for an array of objects)<br />
      GOOD: $i (but only in little loops)<br />
      <br />
      BAD: $Quiz <br />
      BAD: $aReallyLongVariableNameWithoutAGoodReason<br />
      BAD: $error_string</font></p>
  </li>
  <li class="spaced"><strong>Function names</strong> should be simple English 
    lowercase words, and start with the name of the stack and then the module to avoid conflicts, either with
    othe parts of the code or future applications. 
    Words should be separated by underscores. Parameters should always have sensible 
    defaults if possible. Note there is no space between the function name and 
    the following (brackets). <br />
    <p class="examplecode"> <font color="#007700">function </font><font color="#0000BB">forum_set_display_mode</font><font color="#007700">(</font><font color="#0000BB">$mode</font><font color="#007700">=</font><font color="#0000BB">0</font><font color="#007700">) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;global </font><font color="#0000BB">$USER</font><font color="#007700">, 
      </font><font color="#0000BB">$CFG</font><font color="#007700">;<br />
      <br />
      &nbsp;&nbsp;&nbsp;&nbsp;if (</font><font color="#0000BB">$mode</font><font color="#007700">) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#0000BB">$USER</font><font color="#007700">-&gt;</font><font color="#0000BB">mode 
      </font><font color="#007700">= </font><font color="#0000BB">$mode</font><font color="#007700">;<br />
      &nbsp;&nbsp;&nbsp;&nbsp;} else if (empty(</font><font color="#0000BB">$USER</font><font color="#007700">-&gt;</font><font color="#0000BB">mode</font><font color="#007700">)) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#0000BB">$USER</font><font color="#007700">-&gt;</font><font color="#0000BB">mode 
      </font><font color="#007700">= </font><font color="#0000BB">$CFG</font><font color="#007700">-&gt;</font><font color="#0000BB">forum_displaymode</font><font color="#007700">;<br />
      &nbsp;&nbsp;&nbsp;&nbsp;}<br />
      }</font></p>
  </li>
  <li class="spaced"><strong>Blocks</strong> must always be enclosed in curly 
    braces (even if there is only one line). STACK uses Moodle's style: 
    <p class="examplecode"> <font color="#006600">if (</font><font color="#0000CC">$quiz</font><font color="#006600">-&gt;</font><font color="#0000CC">attempts</font><font color="#006600">) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;if (</font><font color="#0000CC">$numattempts </font><font color="#006600">&gt; 
      </font><font color="#0000CC">$quiz</font><font color="#006600">-&gt;</font><font color="#0000CC">attempts</font><font color="#006600">) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#0000CC">error</font><font color="#006600">(</font><font color="#0000BB">$strtoomanyattempts</font><font color="#006600">, 
      </font><font color="#CC0000">"view.php?id=$cm</font><font color="#006600">-&gt;</font><font color="#CC0000">id"</font><font color="#006600">);<br />
      &nbsp;&nbsp;&nbsp;&nbsp;}<br />
      }</font></p>
  </li>
  <li class="spaced"><strong>Strings</strong> should be defined using single quotes 
    where possible, for increased speed.<br />
    <p class="examplecode"> <font color="#006600">$var = 'some text without any 
      variables';<br />
      $var = &quot;with special characters like a new line \n&quot;;<br />
      $var = 'a very, very long string with a '.$single.' variable in it';<br />
      $var = &quot;some $text with $many variables $within it&quot;; </font></p>
  </li>
  <li class="spaced"><strong>Comments</strong> should use two or three slashes 
    and line up nicely with the code. 
    <p class="examplecode"><font color="#006600">function </font><font color="#0000BB">forum_get_ratings_mean</font><font color="#007700">(</font><font color="#0000BB">$postid</font><font color="#007700">, 
      </font><font color="#0000BB">$scale</font><font color="#007700">, </font><font color="#0000BB">$ratings</font><font color="#007700">=</font><font color="#0000BB">NULL</font><font color="#007700">) 
      {<br />
      </font><font color="#FF8000">/// Return the mean rating of a post given 
      to the current user by others.<br />
      /// Scale is an array of possible ratings in the scale<br />
      /// Ratings is an optional simple array of actual ratings (just integers)<br />
      <br />
      &nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#007700">if (!</font><font color="#0000BB">$ratings</font><font color="#007700">) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#0000BB">$ratings 
      </font><font color="#007700">= array(); &nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#FF8000">// 
      Initialize the empty array</font><font color="#007700"><br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;if (</font><font color="#0000BB">$rates 
      </font><font color="#007700">= </font><font color="#0000BB">get_records</font><font color="#007700">(</font><font color="#DD0000">"forum_ratings"</font><font color="#007700">, 
      </font><font color="#DD0000">"post"</font><font color="#007700">, </font><font color="#0000BB">$postid</font><font color="#007700">)) 
      {<br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#FF8000">// 
      Process each rating in turn</font><font color="#007700"><br />
      &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;foreach 
      (</font><font color="#0000BB">$rates </font><font color="#007700">as </font><font color="#0000BB">$rate</font><font color="#007700">) 
      {</font> <br />
      ....etc </p>
  </li>
  <li class="spaced"><strong>Space</strong> should be used liberally - don't be 
    afraid to spread things out a little to gain some clarity. Generally, there 
    should be one space between brackets and normal statements, but no space between 
    brackets and variables or functions:<br />
    <p class="examplecode"> <font color="#007700">foreach (</font><font color="#0000BB">$objects 
      </font><font color="#007700">as </font><font color="#0000BB">$key </font><font color="#007700">=&gt;</font><font color="#0000BB"> 
      $thing</font><font color="#007700">)</font><font color="#006600"> {<br />
      </font><font color="#007700">&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#0000BB">process($thing);</font><font color="#006600"> 
      <br />
      } <br />
      <br />
      </font><font color="#007700">if (</font><font color="#0000BB">$x </font><font color="#007700">== 
      </font><font color="#0000BB">$y</font><font color="#007700">)</font><font color="#006600"> 
      {<br />
      </font><font color="#007700">&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#0000BB">$a 
      </font><font color="#007700">= </font><font color="#0000BB">$b</font><font color="#007700">;</font><font color="#006600"><br />
      } else if (</font><font color="#0000BB">$x </font><font color="#007700">== 
      </font><font color="#0000BB">$z</font><font color="#006600">) {<br />
      </font><font color="#007700">&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#0000BB">$a 
      </font><font color="#007700">= </font><font color="#0000BB">$c</font><font color="#007700">;</font><font color="#006600"><br />
      } else {<br />
      </font><font color="#007700">&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#0000BB">$a 
      </font><font color="#007700">= </font><font color="#0000BB">$d</font><font color="#007700">;</font><font color="#006600"><br />
      } </font></p>
  </li>
</ol>
<p>&nbsp;</p>

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

include('en_doc.php'); 

?>
<h1>Question documentation</h1>

A <tt>stackQuestion</tt> is the basic object in the system. Indeed,
STACK is designed as a vehicle to manage these questions. 
Each question contains a number of fields. 
This page is a reference for each field.

<p>If you would like some examples of how to author questions, 
please refer to the authoring guide instead.</p>  

Each field in the question has attributes. There is a <tt>type</tt>, and 
whether or not the field is <tt>required</tt> in a valid question. (Note, the type 
of a field, should not be confused with the "type" of a question!)

<h3><tt>type</tt></h3>

There are four main types which occur in a <tt>stackQuestion</tt>. Other types occur as
required.

<ul> 

<li> <tt>casstring</tt> is an expression which will be processed 
by the cas, and is required to be in CAS syntax.  Hence in a 
particular question, this information may well be (indeed is likely to be)
cas-specific.  
<br />When processed by the cas, the result is stored as an array containing  
the <tt>value</tt>, essentially an un-parsed form of the evaluated expression
suitable to be fed back to the CAS, together 
with a <tt>display</tt> field which is the HTML (or MathML) code for the
displayed expression.  An <tt>errors</tt> field may or may not be present. 
There are two processes of checking for errors.
  <ol> <li> PHP-side processing.  This checks for mis-matched parentheses, missing * signs
       and generally does its best not to attempt to evaluate a syntactically incorrect 
       expression.</li>
       <li> cas-side processing, of course may generate errors when the evaluation takes
       place.  </li></ol>

<li> <tt>castext</tt> is a LaTeX string in which some computer 
algebra strings have been embedded. These strings are embedded 
between @ characters. Each of these is treated as a 
<tt>casstring</tt>. For example,

<pre> The expansion of $(x-1)^6$ is @expand( (x-1)^6 )@.</pre> 

There is a filter which processes <tt>castext</tt> in the context 
in which it occurs. This context includes a list of variables, and options
for the display. </li>

<li> <tt>rawkeyval</tt> and <tt>keyval</tt> pair. These 
fields always occur together. The former is the string input, 
typed by the user. The latter is the PHP array of values. An 
example is the field <tt>questionVars</tt>.

</li> 
<li> <tt>meta</tt> These fields are information about the question.
For example, the questionID number, who edited the question and so on. These
fields appear in the database directlty, while the others are serialized together
and stored in the <tt>questionBody</tt>. Indeed, 
this field is used to create the database tables in the first place. </li>

</ul>

<?php

   foreach( $stackQuestion as $field => $q_field)
   {
   $fd = 'stackQuestion_'.$field;
   $fd = get_string($fd,'stack','');
   echo "<h3>$fd</h3>";
   echo $q_field['doc'];
   echo "<p>";
      echo "Name of field: <font color=orange><tt>$field</tt></font>.  Type of field:  <font color=orange><tt>$q_field[type]</tt></font>.  Required:  <font color=orange><tt>$q_field[required]</tt></font>.";
   }

?>

<h2>Data type stackQuestionInst</h2>

A <tt>stackQuestionInst</tt> is an instantiated version of a 
<tt>stackQuestion</tt>. It inherits many fields from the 
<tt>stackQuestion</tt>. There are also many fields with the 
string \"<tt>Inst</tt>\" appended to the field name, to indicate 
they are instantiated versions.

For example, <tt>questionVarsInst</tt> are the <tt>questionVars</tt> with their values 
assigned.

Fields in a <tt>stackQuestion</tt> of type <tt>rawkeyvals</tt> are not 
inherited by the </tt>stackQuestionInst</tt>. There is no 
point storing stings, when we have the parsed, validated <tt>keyvals</tt> fields to work with.

<?php
 foreach( $stackQuestionInst as $field => $q_field)
 {
 echo $q_field['doc'];
 echo "";
 echo "Name of field: <tt>$field</tt>. Type of field: <tt>$q_field[type]</tt>. Required: <tt>$q_field[required]</tt>.";
 }

?>

<h2>Data type stackQuestionAttempt</h2>

This holds data about each student's attempts as a particular <tt>questionInst</tt>. Note that in a fully correct relational database, these would be held in a separate table. However, since each student will generate a new instance, it seems better to store the attempts as an array subfield of the <tt>questionInst</tt> itself. This field is

<?php
 foreach( $stackQuestionAttempt as $field => $q_field)
 {
 echo "Name of field: <tt>$field</tt>. Type of field: <tt>$q_field[type]</tt>. ";
 echo $q_field[doc];
 }

//echo "<pre>";print_r($stackQuestionInst);echo "</pre>";

?>

--- NEW FILE: author_gettingstarted.php ---
<?php
/** 
* An authoring guide for STACK questions.
*
* @package documentation
* @subpackage Stack
*/

require('html/trypopupform.html'); 
include_once("$stack_root/scripts/stackAuthor.php"); 
include_once("{$stack_root}/scripts/maxima/maximafun.php");

/** 
* Display an example of the stack question
*
*
* @question The question to be displayed.
* 
*/
function stack_doc_dispexample($question) {
  global $stackQuestion;

  //show_array($question);

  echo "<table border='1'>\n";
  foreach ($question as $key => $val) {
      echo "<tr>\n <td>";
      echo "<a href=\"javascript:HelpPopup('$key','stackQuestion');\">{$stackQuestion[$key]['descript']}</a></td>\n";
      echo " <td><tt>$val</tt> </td>\n</tr>\n";
  }
  echo "</table>\n";
}

/** 
* Display, with hyperlinking, the STACK question field name and a link to the help pop-up.
*
*
* @param string $command The command to be displayed
* @param string $stackhelp Optional: the help file which contains the field.
*/
function stack_doc_dispstackqfield($command,$stackhelp='stackQuestion') {
  global $stackQuestion,$stackQuestionPotResp,$stackOptions;

  if ('stackQuestion' == $stackhelp) {
      $descript = $stackQuestion[$command]['descript'];
  } else if ('stackQuestionPotResp' == $stackhelp) {
      $descript =  $stackQuestionPotResp[$command]['descript'];
  } else if ('stackOptions' == $stackhelp) {
      $descript =  $stackOptions[$command]['descript'];
  }

  echo "<a href=\"javascript:HelpPopup('$command','$stackhelp');\">$descript</a> ";

}

/** 
* Display, with hyper-linking, the STACK command
*
*
* @param string $command The command to be displayed
*/
function stack_doc_dispstackcommand($command) {

  echo "<a href=\"#STACK_command_{$command}\"><font color=\"orange\"><tt>$command</tt></font></a> ";

}

?>

<h1><a name=\"author\">Authoring a STACK question</a></h1>

A <tt>stackQuestion</tt> is the basic object in the system. Indeed,
STACK is designed as a vehicle to manage these questions. This page explains the process
of authoring a question, by working through an example. This example uses the online form
method. It is possible to edit XML files directly, but this process is not explained here.

<h2>A minimal example</h2>

Start with a <a href="javascript:NewPopup();">New question</a>. This link will open a pop-up window
in which you can edit the question. This link also occurs in the Demonstration &gt&gt Question Bank page.
Do not be put off by the fact this form looks complicated. There are lots of fields,
but only two are compulsory:
<ol>
<li>The <?php stack_doc_dispstackqfield('questionStem'); ?> is the string actually displayed to the
student. ie this is "the question".</li>
<li>The <?php stack_doc_dispstackqfield('questionAns'); ?> is the answer to the question.</li>
</ol>

We are now ready to edit a new question. 
Into these two fields, enter the following information. 
It should be possible to cut and paste.

<?php 
$question = array();
$question['questionStem'] = 'Differentiate $(x-1)^3$ with respect to $x$.';
$question['questionAns']  = '3*(x-1)^2';

stack_doc_dispexample($question);

?>

Scroll down and click the "edit question" link. Now check for 
any errors, which should appear under the respective field in 
red, if so correct them and press "edit question" again. When 
you are in a position to, click the "Try this question" link. 
This will take you into another view: the "teacher's view" mode. 
Click on "validate" and "mark" with different answers. Of course, 
you can return to the edit form by pressing "edit". The 
"new_version" is to create a different random version, something 
we shall cover in a moment.

<p>You now have a minimal question working.</p>

Note, this question will only remain as long as you are in a 
session. In order to store the question in STACK's database you 
need to be logged in as the admin user. Note that currently if 
you want to store a question you need to login before 
you start to edit. If you forget to do this all is not lost: 
download your temporary question as an XML file from the question 
edit page, and login. They you can import is back to the 
database.

<h2>CAS-enabled text: <tt>castext</tt></h2>

Before we consider in detail how to add more features to the 
question we introduce a datatype <tt>castext</tt>. Many of the 
fields in a STACK question, such as the <?php 
stack_doc_dispstackqfield('questionStem'); ?> are of this nominal 
type, which can be thought of as CAS-enabled text. This 
is simply LaTeX text, in which CAS commands can be embedded. 
These CAS commands are executed before the question is displayed 
to the user.

Use only simple LaTeX structures, and equations. 
Only core LaTeX is supported, and experienced users may feel a 
little disappointed that not all the more complex environments, 
(such as \begin{eqnarray}) work. If you do not know how to use 
LaTeX, some simple examples are given in the <a 
href="#FAQ">FAQ</a>.

The following things to remember about <tt>castext</tt>:
<ul>
<li>Anything enclosed between @ symbols is evaluated by the CAS, and displayed using the
display option as an inline equation. This is analogous to using LaTeX's $'s. 
Note however, that you don't need to use 
<tt>$@ stuff @$</tt>, and that <tt>@ stuff @</tt> is sufficient.</li>
<li>To get a displayed equation centered on a line of its own, use either
<tt>$$@ stuff @$$</tt>, <tt>\[@ stuff @\]</tt>,as in LaTeX.</li>
<li> Anything between <tt>&lt html> stuff &lt html></tt> structures is kept as HTML, and not
interpreted as LaTeX. This enables URL's to be included in the text, as well as external images etc. </li>
</ul>

<h2>Random questions</h2>

It is common to want to use random numbers in questions. This 
is straight forward to do, and we make use of the optional 
 <?php stack_doc_dispstackqfield('questionVarsRaw'); ?> field. 
 Please click on the link to the left to read the specific 
documentation on this field. More examples are given 
 <a href="#qvars_ex">later</a>.

To create a random question we need to modify the previous one slightly so that the fields consist of the following.
Note, that while a little more complex, this question is no different from the one before.
<?php
$question = array();
$question['questionVarsRaw'] = 'p = (x-1)^3'; 
$question['questionStem'] = 'Differentiate @p@ with respect to $x$.';
$question['questionAns'] = 'diff(p,x)';

stack_doc_dispexample($question);

?>
Notice that now we have defined a local variable p, and used the value of this 
in the <?php stack_doc_dispstackqfield('questionStem'); ?>. 
Hence, the user will not see a "p" on the screen when the question
is instantiated, but the value of p.

Notice also that in the 
 <?php stack_doc_dispstackqfield('questionAns'); ?>, 
there is a CAS command to differentiate the value of p with
respect to x. It is necessary for the CAS to work out the answer in a random question.

We are now in a position to generate a random question. Use the data, as follows.

<?php
$question = array();
$question['questionVarsRaw'] = "n = 2+rand(3); p = (x-1)^n"; 
$question['questionStem']    = 'Differentiate @p@ with respect to $x$.';
$question['questionAns']     = 'diff(p,x)';

stack_doc_dispexample($question);

?>
In this new example, we have an extra variable n which is defined to be a random number. 
This is then used to define the variable p which is in turn used in the question itself. Edit
your trial question, and in the Teacher's trial window use the "new version" button to get new random versions
of the question.

When generating random questions in CAA we talk about 
random numbers when we really mean pseudo-random 
numbers. To keep track of which random numbers are 
generated for each user, there is a special command in STACK, 
which you should use instead of Maxima's random command. This is 
the <?php stack_doc_dispstackcommand("rand"); ?> command which is 
a general "random thing" generator. It can be used to generate 
random numbers and also to make selections from a list.

As a specific example of some of these features, try the 
question illustrated below. This contains random numbers, and 
also examples of variables and expressions selected from a list. 
<?php $question = array(); $question['questionVarsRaw'] = "n = 
rand(5)+3; v = rand([x,s,t]); p = rand([sin(n*v),cos(n*v)])"; 
$question['questionStem'] = 'Differentiate @p@ with respect to 
@v@.'; $question['questionAns'] = 'diff(p,v)';

stack_doc_dispexample($question);

?> </p>

<h2><a name="author_potential_response">Better feedback via the potential response tree</a></h2>

So far we have just compared the student's answer with that of the teacher. This gives the 
minimum possible feedback, along the lines of "correct" or "incorrect". STACK has a mechanism
for you to provide better feedback, and this facility is one of STACK's more important features.

In our question we need to find the section of the form which looks like
<hr />
<a href="#author_potential_response">Add</a>
<input type="input" name="questionPotResp[add]" value="0" size="3" /> 
<a href="javascript:HelpPopup('all','stackQuestionPotResp');">potential responses.</a> (distracters etc). 
<hr />
In this change the 0 to a 2 in the box on the question edit form (not above!) and activate 
either the "Add" or "Edit question" links. The question edit form will become quite significantly more complex
as now you have just added two <a href="javascript:HelpPopup('all','stackQuestionPotResp');">potential responses.</a> 
It is worth reading the documentation about the 
<a href="javascript:HelpPopup('all','stackQuestionPotResp');">potential responses</a> 
before we proceed to examples which illustrate this.

<p>As an example, we shall provide feedback which checks
<ol>
<li>For the correct answer.</li>
<li>To see if the student integrated by mistake.</li>
</ol>

First, check that a variable name appears in the 
<?php stack_doc_dispstackqfield('questionAnsKey'); ?>, it will
probably read <tt>ans1</tt>. Use this variable name to refer to the student's answer 
in all subsequent work.

<p>Ignore, for now, the <?php stack_doc_dispstackqfield('questionAnsVarsRaw'); ?> field, since
we do not need to process the student's answer yet.</p>

Check the first potential response box, indexed with a No. 0 in the top left hand corner. 
Assuming you have been following this tutorial, you should find that the box 
<?php stack_doc_dispstackqfield('SAns','stackQuestionPotResp'); ?> contains the student's answer,
expressed as <tt>ans1</tt> and that <?php stack_doc_dispstackqfield('TAns','stackQuestionPotResp'); ?>
contains the teacher's answer <tt>diff(p,x)</tt>. Notice that this depends on the variable <tt>p</tt> and
also contains a CAS command <tt>diff</tt>, as before.

Change the <?php stack_doc_dispstackqfield('AnsTest','stackOptions'); ?> to be <tt>AlgEquiv</tt> (algebraic
equivalence test), since although this is the default, we now want to be certain this test is actually used.
Leave the <?php stack_doc_dispstackqfield('AnsTestOpt','stackOptions'); ?> blank, since in this case we 
need no options for the Answer Test.

DO NOT check the Del box! which would result in this potential response being deleted on the next edit cycle.
We are now in a position to decide what outcomes we would like. If the result of this answer test is true, we have
established the student's answer is correct. Hence we would like to give one mark. This is achieved by
setting the <?php stack_doc_dispstackqfield('RawMarkMod','stackQuestionPotResp'); ?> (labelled "Mark") to be '=', 
and the 
<?php stack_doc_dispstackqfield('RawMark','stackQuestionPotResp'); ?> to be 1. Notice, these fields
already assume these values by default, so you should not need to do anything.
Since we have established that the answer is correct we end the process by choosing the Next field to be -1.
Again it already is.

What if the answer test was false? We would like to check that the student has not integrated by
mistake, and we achieve this by applying another answer test in the potential response node No. 1. To jump to this
node, from the false branch of Node No 0., make sure that the "Next" field is set to be 1. 
This fragment is shown below.

<hr />
<table>
<tr align=top><td>If...</td>
             <td><a href="javascript:HelpPopup('RawMarkMod','stackQuestionPotResp');">Mark</a></td>
             <td><a href="javascript:HelpPopup('RawMark','stackQuestionPotResp');">Value</a></td>
             <td><a href="javascript:HelpPopup('Penalty','stackQuestionPotResp');">Penalty</a></td>
             <td colspan='2'><a href="javascript:HelpPopup('FeedBack','stackQuestionPotResp');">Feedback</a></td>
             <td><a href="javascript:HelpPopup('ApLat','stackQuestionPotResp');">Next</a></td>
<td></td></tr>
<tr> <td colspan = '4'>............</td></tr>
<tr><td>false</td><td>  <select name="questionPotResp[0][false][RawMarkMod]">  <option value="=" selected>=</option>
  <option value="+">+</option>

  <option value="-">-</option>
  <option value="=AT">=AT</option>
  </select></td>
 <td><input type='text' name='questionPotResp[0][false][RawMark]' size ='4' value='0' /></td>
<td><input type='text' name='questionPotResp[0][false][Penalty]' value ='' size =' 3' /></td>
 <td colspan='2'><textarea name='questionPotResp[0][false][FeedBack]' rows ='1' cols='50'></textarea></td>
<td>
  <select name="questionPotResp[0][false][ApLat]">
  <option value="-1">-1</option>

  <option value="0">0</option>
  <option value="1" selected>1</option>
  </selected></td>
</tr></table><hr />

We are now in a position to implement the second test, before we do this we need to decide what we want.</p>

If the student has integrated, they may or may not have added a constant of integration. If that have
added such a constant we don't know what they have used! So, the best way to solve this problem is to
differentiate their answer and compare it to the question. This is achieved with the following potential response node.
You should examine this carefully, and transfer the values to your question template.

<?php
$pr = array( 'SAns' => 'diff(ans1,x)','TAns' => 'p','AnsTest' => 'AlgEquiv', 'order' => '1',
             'true' => array( 'RawMarkMod' => '=',
                              'RawMark' => '0',
                              'FeedBack' => 'It looks like you have integrated instead!  Please try again.',
                              'ApLat' => '-1'),
             'false' => array( 'RawMarkMod' => '=',
                               'RawMark' => '0',
                               'ApLat'   => '-1')
            );

 $errors = array();
 @stack_question_edit_potresp('1',$pr,'2',$errors); 

?>

Another common problem is that, even if the student has given the correct answer, they may 
have used a quite inappropriate method. For example, they may have expanded out the polynomial
and hence give the answer in unfactored form. In this situation, we might like to provide some 
encouraging feedback to explain to the student what they have done wrong.

First, we need to add another potential response: after all, we need to apply another answer
test. To do this, go back and Add 1 potential response in a similar way as before. 
After you have re-loaded the page with the "Add" or "Edit question" link, you should have three
potential responses for this question.

To use this potential response, edit Node 0, and now change the true branch to make the Next node 
point to the new Node 2. If we enter Node 2, we know the student has the correct answer. We only need
to establish if it is factored or not.

To establish that the student's answer is factored we need to use a different 
<?php stack_doc_dispstackqfield('AnsTest','stackOptions'); ?>
In this case we choose <tt>SA_factored</tt> which establishes that the Student's Answer is in
factored form. Note that this is similar to the <tt>FacForm</tt> answer test, but it does not 
provide feedback. Since the purpose of this question is not to see if a student can factor the answer
we wish to provide our own feedback. We need to add <tt>x</tt> to the 
<?php stack_doc_dispstackqfield('AnsTestOpt','stackOptions'); ?> to indicate which
variable we are using.

<p>We also need to update the marks, since we know the student has the answer correct, we should make sure
they get marks in both branches of the potential response node.</p>

Last, but certainly not least, we add some positive and encouraging feedback to the false branch.
For reference, my node 2. is shown below.

<?php
$pr = array( 'SAns' => 'ans1','TAns' => 'diff(p,x)','AnsTest' => 'SA_factored',
             'AnsTestOpt' => 'x', 'order' => '2',
             'true' => array( 'RawMarkMod' => '=',
                              'RawMark' => '1',
                               'ApLat' => '-1'),
             'false' => array( 'RawMarkMod' => '=',
                               'RawMark' => '1',
                               'FeedBack' => 'You should keep your answer in factored form.  
In this case there is no need to expand out your
answer, since the chain rule will help you
to differentiate the expression directly.',
                               'ApLat'   => '-1')

            );

 $errors = array();
 @stack_question_edit_potresp('1',$pr,'2',$errors); 

?>

Of course, you can continue to add more potential responses as the need arises. These can test
for more subtle errors, based upon the common mistakes student's make. In each
case an <?php stack_doc_dispstackqfield('AnsTest','stackOptions'); ?> can be used to make
a different kind of distinction between answers. You can also define
 <?php stack_doc_dispstackqfield('questionAnsVarsRaw'); ?> before the response processing tree
is traversed to perform calculations on the student's answer.

<h2>Options</h2>

There is a tension between system flexibility and the simplicity 
of the question authoring process. At one end of this spectrum, 
it should be possible in each question to alter every system 
feature, from the question stem, answer and number of marks 
available right through to the fonts used, teacher's email 
address and the URL for a help page. At the other end of the 
spectrum, questions need to be authored with a maximum of 
efficiency. Really, the only compulsory fields need be: 
 <ol> 
 <li>the question stem: i.e. the actual "question" posed to the student, and</li>
 <li>the answer.</li>
 </ol>
One challenge was to make it possible to author a viable question 
by only entering this information, and provide a mechanism for 
other features to adopt sensible default values taken from a 
context.

The solution is a cascading options structure. Options are 
essentially global variables available for use by questions and 
quizzes. They assume a default value at the system level which 
can be overridden at the quiz level, or again at the question 
level. Although we conceived of a "subject", "quiz", 
"question" hierarchy, the cascading options structure is flexible 
enough to cope with any navigation system which is essentially a 
tree structure. When authoring a question or quiz, you can use 
the default values to create new questions and quizzes quickly 
and consistently. In fact, most things turn out to be best represented
as an option, including the 
<?php stack_doc_dispstackqfield('QuVal','stackOptions'); ?> (no. of marks),
<?php stack_doc_dispstackqfield('Penalty','stackOptions'); ?>, and even the
<?php stack_doc_dispstackqfield('AnsTest','stackOptions'); ?>.
There are a wide variety of 
options, with specific documentation available 
<a href="index.php?action=help&field=stackOptions">here</a>.

The options allow a single question to behave in quite different 
ways, depending on the values set. 
Adding new options is a reasonably straightforward, and if STACK does 
not behave in the way you would like, please propose an alternative
and it may be added as an option for others to enjoy.
Note that this option structure is somewhat at odds with the ISM
Question and Test Interpretability (QTI) view of an assessment
item as being entirely self contained.

<?php 
 // Examples and documentation for the Question Variables.
 $descript = $stackQuestion['questionVarsRaw']['descript'];
 echo "<h2><a name=\"qvars\">$descript</a></h2>\n";
 echo $stackQuestion['questionVarsRaw']['doc']; 
?>

<h2><a name="qvars_ex">Examples</a></h2>

<p>Simple assignments are of the form  <tt>key = value</tt>, for 
example, 
 <pre>n = rand(3)+2
p = (n-1)^n</pre>

Of course, these assignments can make use of Maxima's functions 
to manipulate expressions.
 <pre>p = expand( (x-3)*(x-4) )</pre>

You can use Maxima's looping structures within Question 
variables, although the syntax requires this to be of the form 
<tt>key = value</tt>. In this case, the <tt>key</tt> will be 
assigned the value <tt>DONE</tt> at the end of the process, 
unless another value is returned. For example 
 <pre>n = 1
dum1 = FOR a:-3 THRU 26 STEP 7 DO n:n+a </pre>

Note, you must use Maxima's syntax <tt>a:-3</tt> here for 
assignment of <tt>-3</tt> to the variable <tt>a</tt>. The 
assignment to the dummy variable <tt>dum1</tt> is to ensure every 
command is of the form <tt>key = value</tt>.

Please look at Maxima's documentation for the command 
<?php         
 $url = $maxima_cmd['DO']['urls'][0];
 echo " <a href='maximadocs/maxdoc/$url'>DO</a>.</p> ";
?>

You should also look at Maxima's <?php 
 $url = $maxima_cmd['BLOCK']['urls'][0];
 echo " <a href='maximadocs/maxdoc/$url'>BLOCK</a>";
?> which may be useful here for more complex manipulations. Here is another example,
which generates a random polynomial.

<pre>
m = rand([y,x,t])
p = rand(7)+1
q = 0
dum1 = block(for i:1 while i<=p do (q:q+rand(9)*m^p,p:p-1),return(q))
r = int(q,m)
</pre>

It is also possible to define functions within the Question 
Variables for use within a question. This is not recommended, 
and has not been widely tested. For example 
 <pre>dum1 = f(x) := x^2 
n = f(4)</pre> Again, the syntax requires this to be of the form 
<tt>key = value</tt>, so that another dummy assignment has taken 
place. Please look at Maxima's documentation for <?php 
 $url = $stack_web_url."maximadocs/maxdoc/maxima_39.html#SEC120";
 echo " <a href='$url'>functions</a>. ";
?>

--- NEW FILE: student_practicemode.php ---

  <a name="practice"><h2>Practice mode</h2></a>

If a test is set up in practice mode, it will say so in the test
 selection menu, and also at the top of the test page. If so, you
 can do the same set of questions repeatedly, and mark them by
 clicking the Mark button at the bottom of the page. The
 system will tell you whether your answers are right or wrong (except
 for multiple choice questions) and may give some feedback about any
 answers that are wrong, but it will not tell you the right answers.
 You can click the Back button on your browser to get back to
 the page where you filled in your answers, correct any mistakes, and
 try again. Alternatively, you can go away and come back some other
 time; Stack will remember your previous answers, so you can
 correct any that were wrong, and leave the others as they are. The
 system will give you a numerical mark for your work which you may
 find informative, but it does not officially count for anything.
 For more information about the marking system, see the section on 
 <a href="#assessment">assessment mode</a>.

  <br /><br />

If you want to see the solutions, you can click the Solutions
 button at the bottom of the page instead of the Mark button. 
 If you try the test again after doing this, you will get slightly
 different questions.

--- NEW FILE: student_overview.php ---

<H1>Help with STACK</H1>

  <a name="overview"><h2>Overview</h2></a>

Stack is a computer system that assists in the teaching of
 some parts of University mathematics.

  <br /><br />

The basic idea is that you follow the links and
 then Stack will present you with a list of questions. There is
 detailed advice below on how to enter your
 answers. You can then click the Mark button at the
 bottom of the page to mark your work. The details of how this works
 depend on whether Stack is running in practice mode or assessment mode.

--- NEW FILE: about_install.php ---
<?php
/** 
* Details of how to install STACK.
*
* @package documentation
* @subpackage STACK
*
*/

?>

<h1>Installing STACK</h1>

STACK is a collection of PHP scripts, which link together the 
user, a CAS, and a database over the internet. Hence the system 
itself requires of a number of extra components.

<h3>Platform</h3>

The scripts currently released will run on a Linux (or unix) 
machine or a Microsoft (Windows) platform.

<ul>
<li>Linux: STACK has been tested on a <a href="http://fedora.redhat.com/">Fedora</a>
based Linux system running the Apache web server.</li>
<li>Microsoft: STACK has been tested on Windows XP and Windows 2000 using 
IIS and <a href="http://www.easyphp.org/">EasyPHP</a>. EasyPHP is by far the easiest
platform on which to install STACK. However, this does not seem to be as efficient as Linux and
may not be suitable for a production server.</li>
</ul>

<h3>Components</h3>

Regardless of which operating system used, you will need the following components.
<ul>
<li>A web server, such as <a href="http://www.apache.org/">Apache</a>, 
running <a href="http://www.php.net/">PHP</a> (at least version 4.3.9), </li>
and <a href="http://www.mysql.com/">MySQL</a> server (at least version 4). 
Windows users could use <a href="http://www.easyphp.org/">EasyPHP</a>.</li>
<li>You need to convex LaTeX to HTML with <a href="http://hutchinson.belmont.ma.us/tth/">TtH</a>. 
<li>The computer algebra system (<a href="#cas">see below</a>)
<a href="http://maxima.sourceforge.net/">Maxima</a>. Version 5.9.1 (or later) is needed to include graphical support.
(Note, for those on a Microsoft platform, the <a href="http://wxmaxima.sourceforge.net/">wxMaxima</a>
front end is much better than that distributed with Maxima itself and is well worth installing for
testing CAS code outside STACK)</li>
<li>For graphical support we have used the <a href="http://www.gnuplot.info/">GNUPLOT</a> package. (Note, this 
is already supplied on Fedora 3 distributions, and comes with Maxima 5.9.1 on Windows)
</ul>
Finally of course
<ul>
<li>The STACK scripts themselves.</li>
</ul>

The latest stack scripts can be obtained from the CVS on 
<tt>sourceforge</tt>. For example, anonymous access is via

<p><tt>cvs -z3 -d:pserver:ano...@cv...:/cvsroot/stack 
co -P  <?php echo $stack_ver['cvsmodule'] ?> </tt></p>

<p> Developer access can be obtained via SSH by</p>

<p><tt>export CVS_RSH=ssh<br /> 

cvs -z3 -d:ext:</tt><em>developername</em><tt>@cvs.sourceforge.net:/cvsroot/stack co -P 
<?php echo $stack_ver['cvsmodule'] ?> </tt></p>

Users of a Microsoft platform should consider using the <a href="http://www.tortoisecvs.org/">tortoise CVS</a>
application to obtain the scripts. Details of fields to fill in are available
on this <a href="doc/stackcvs.png">screen shot</a>. Note: the module name (underlined in red)
should read <?php echo $stack_ver['cvsmodule'] ?>

<h2>Security</h2>

WARNING! What these scripts attempt to 
do is inherently insecure. This system is designed to 
execute arbitrary third party CAS code on your server, to create 
mathematical questions. This is inherently insecure, and you 
should be aware of the dangers. These are in addition 
to the normal security problems associated with interactive, 
database driven web sites.

<p>The array 

<pre>$stack_cas['globalForbid']</pre>

is generated automatically and contains strings the system 
attempts not to execute. You should look at the file 
<tt>scripts/maxima/maximafun.php</tt> and the array distributed, 
together with the CAS documentation, to decide which CAS commands 
you wish to prevent from being executed on your server. This 
list is not comprehensive, and you should make your own decisions 
here. You have been warned!

<h2><a href="http://www.php.net/">PHP</a></h2>

STACK needs no special PHP settings, although the function <tt>proc_open</tt>
must be available to establish a connection with the external applications.

For mail, use the <a href="http://pear.php.net/">pear 
class</a>. For example in Linux, to install this from the 
command line, type <tt>pear install mail</tt>, for example. 
You will need to install, <tt>mail, NET_Socket, NET_SMTP, 
Auth_SASL</tt>.

<!--
<p>There are two ways to use the scripts, as follows.</p> 

<h3>1. A direct connection with the CAS.</h3>

This is the method used when <tt>$stack_os</tt> is set to be 
either of <tt>'win'</tt> or <tt>'unix'</tt>. Each request to the 
CAS starts up and shuts down a CAS process. Note, each item may 
use the CAS on many occasions when traversing the potential 
response tree to mark a student's answer.

<h3>2. Starting a pool of CAS processes.</h3>

This method uses command line PHP to open and manage a pool of 
CAS processes. The scripts then connect to the pool using 
sockets on the local machine. To use this method, 
<tt>$stack_os</tt> is set to be <tt>'unix-pool'</tt>.

This removes the overhead of starting a new CAS process each 
time, and hence loading and compiling all the libraries. However, 
this requires PHP 5 to get access to the process control 
functions to for...

[truncated message content]