Menu
▾
▴
[Stack-cvs] stack-1-0/lang/en/doc about_develop.php,NONE,1.1 about_general.php,NONE,1.1 about_install.php,NONE,1.1 author_answertest.php,NONE,1.1 author_commonsyntax.php,NONE,1.1 author_factsformula.php,NONE,1.1 author_faq.php,NONE,1.1 author_gettingstarted.php,NONE,1.1 author_maxima.php,NONE,1.1 author_options.php,NONE,1.1 author_potresp.php,NONE,1.1 author_questionfields.php,NONE,1.1 en_doc.php,NONE,1.1 help_popup.php,NONE,1.1 stackcvs.png,NONE,1.1 student_assessmentmode.php,NONE,1.1 student_forbidden.php,NONE,1.1 student_input.php,NONE,1.1 student_overview.php,NONE,1.1 student_practicemode.php,NONE,1.1 student_understandingoutput.php,NONE,1.1 student_factsformula.php,1.2,1.3
Update of /cvsroot/stack/stack-1-0/lang/en/doc In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv15328/lang/en/doc Modified Files: student_factsformula.php Added Files: about_develop.php about_general.php about_install.php author_answertest.php author_commonsyntax.php author_factsformula.php author_faq.php author_gettingstarted.php author_maxima.php author_options.php author_potresp.php author_questionfields.php en_doc.php help_popup.php stackcvs.png student_assessmentmode.php student_forbidden.php student_input.php student_overview.php student_practicemode.php student_understandingoutput.php Log Message: Moved the documentation --- 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><b>Linux:</b> STACK has been tested on a <a href="http://fedora.redhat.com/">Fedora</a> based Linux system running the Apache web server.</li> <li><b>Microsoft:</b> 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), <!--(version 5 if using the CAS Pool)--></li> and <a href="http://www.mysql.com/">MySQL</a> server (at least version 4.1).<br /> 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, version 4.0. (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> <p>The <em>latest</em> stack scripts can be obtained from the CVS on <tt>sourceforge</tt>. For example, anonymous access is via</p> <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> <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 <font color="red"><?php echo $stack_ver['cvsmodule'] ?></font> <h2>Security</h2> <p><font color="red">WARNING! What these scripts attempt to do is inherently insecure.</font> 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 <em>in addition</em> to the normal security problems associated with interactive, database driven web sites.</p> <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. <font color="red"><em>You have been warned!</em></font> <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. <p>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.<br /> You will need to install, <tt>mail, NET_Socket, NET_SMTP, Auth_SASL</tt>.</p> <!-- <p>There are two ways to use the scripts, as follows.</p> <h3>1. A direct connection with the CAS.</h3> <p>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> <p>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>. </p> <p>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 fork etc, and needs command line access to start and stop the scripts. </p> --> <p> You might also consider the other components of your PHP system. In particular, if you are integrating STACK with a VLE (eg <a href="http://moodle.org/">Moodle</a>, or <a href="http://www.logicampus.com/">Logicampus</a>), then you may need to have installed zlib and libpng (in that order) from downloads.</p> <p>For reference, the Linux test system adopted the following options. <br /><tt>./configure --with-mysql --with-apache --with-gd --with-zlib</tt> </p> <!--<br />For use with a pool of CAS process, the PHP 5 process control functions are required. <br /><tt>./configure --with-mysql --with-apache --with-gd --with-zlib --enable-sockets --enable-pcntl</tt> --> <h2><a href="http://www.mysql.com/">MySQL</a></h2> Please refer to the specific documentation for installing MySQL. There are no special requirements for STACK. If you wish to install STACK with an alternative database, this should be possible. All the interactions with the database are contained in the script <pre>$stack_root/scripts/stackDatabase.php</pre> <h2>Display via the LaTeX system</h2> <p>The basic route to convert the output from the CAS, into a form which is suitable for display has so far been to force the CAS to output LaTeX, and convert this on the fly to HTML. This conversion could be done in a number of ways. Support currently exists for <a href="http://hutchinson.belmont.ma.us/tth/">TtH</a> This is just one solution to the problem of displaying mathematics on the internet. TtH is a closed-source system, but the binary distribution is available for download. There are no special requirements.</p> <p>The package <a href="http://pauillac.inria.fr/~maranget/hevea/">HeVeA</a> could also be used in place of TtH. If you wish to do this, please contact the developers.</p> <p>It would also be possible to have the CAS output MathML, and convert any LaTeX in questions to MathML and HTML using a converter such as TtM. While we have designed STACK with this in mind, we have as yet not implemented this functionality.</p> <h2><a name='cas'>The computer algebra system Maxima</a></h2> <p>STACK has been designed to work with the <a href="http://maxima.sourceforge.net/">Maxima</a> computer algebra system although it should be possible to provide support for others such as <a href="http://www.nongnu.org/axiom/">AXIOM</a>. <p>Maxima is the preferred open source CAS. Version 5.9.1, or later, is needed, to work with the <a href="http://www.gnuplot.info/">GNUPLOT</a> package, for graphical support. <p><b>Linux only:</b> Please read the Maxima documentation carefully, since this package is itself supported in a number of different Lisp implementations. <p><b>Windows only:</b> Setting the PATH in Windows can be a problem, see below for advice with this. <p>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. <!-- <h3>Other CAS systems</h3> <p>To use STACK with different CAS systems is certainly possible. The functions which interact with the CAS are contained in the file <pre>$stack_root/scripts/CASPool/stackCAS.php</pre> If you wish do this, please let the developers know and we may be able to offer more specific support. --> <h2>Installing the PHP scripts and setting up STACK itself</h2> <ol> <li>Place all scripts in a directory visible to the web server. This directory will be referred to as <tt>$stack_root</tt>.</li> <li>Copy the file <tt>$stack_root/stackstd.php.dist</tt> to <tt>$stack_root/stackstd.php</tt><br />This file will contain all your local settings.</li> <li>Edit <tt>$stack_root/stackstd.php</tt> to reflect your local settings. This is the only file you should have to edit, so read carefully the instructions it contains.</li> <li>Create a directory for locally and dynamically generated files. For example, <tt>/home/stack/stacklocal</tt>. Ensure the webserver can write to this, and update the variable, eg <pre>$stack_logfiles = "/home/stack/stacklocal"; </pre> in <tt>stackstd.php</tt>.</li> <li>Create a directory for dynamically generated plots. This needs to be available to users of the internet, so the webserver should be able to serve files from this directory. The default value is assumed to be <pre>$maximalocal['IMAGE_DIR'] = $stack_root.'/tmp/';</pre> ie, you need to create the directory <tt>$stack_root/tmp</tt>. Ensure the webserver can write to this directory. <li><b>Windows: </b>Setting the Windows PATH variable can be a problem. For STACK to work you need to be able to call the following external applications: <ol><li>TtH</li> <li>Maxima</li> <li>gnuplot</li> </ol> Create a directory for these applications, such as <tt>c:\Programe Files\bin</tt>, add this to your PATH, and copy the executables into this. TtH and gnuplot are single executable applications - gnuplot is distributed with Maxima and is the binary file <tt>C:\Program Files\Maxima-5.9.1\bin\wgnuplot.exe</tt> <p> For Maxima, a batch file has been provided: <tt>$stack_root/scripts/install/stackmaxima.bat</tt>. Copy this file into a directory on your Windows PATH, and edit it to point to your current version of Maxima. </li> <li>In <tt>stackstd.php</tt>, edit the entries for the variables which hold information about the MySQL user and database which is to be created and used for STACK. <pre> $stack_mysql['host'] = 'localhost'; $stack_mysql['user'] = 'stack'; $stack_mysql['pswd'] = ''; $stack_mysql['stackdb'] = 'stack'; </pre> In particular you will need to add a password for the mysql user. </li> <li> The MySQL database is setup using the script <tt><a href='scripts/install/stackInstall.php'>$stack_root/scripts/install/stackInstall.php</a></tt>. <p><font color="red">WARNING!</font> This is disabled by default, for obvious reasons, and will do nothing. Edit the file, and comment out line 9, (ie add // to the beginning of the line). When the install is complete, reinstate the line to prevent future third party execution of this script.</p> </ol> <!-- <h3>MySQL setup</h3> Remember that a clean MySQL install requires you to set the root password. For example, <pre> mysql -u root mysql> set password for 'root'@'localhost' = password('newpassword'); mysql> set password for 'root'@'host' = password('newpassword'); mysql> exit </pre> Then reboot. <h3>Starting the Pool of CAS processes</h3> <p>Only if you have chosen <tt>$stack_os='unix-pool';</tt>, you will need to start the pool of CAS processes from the command line. In order to link the pool of CAS processes with the internet it is necessary to run a command line PHP script.</p> <ol> <li> Copy the files <tt>$stack_root/scripts/CASPool/startsocket.php</tt> and <tt>$stack_root/scripts/CASPool/startsocket.php</tt> to somewhere the webserver cannot see.</li> <li>Edit these files to remove the die(); commands.</li> <li>Add a path to <tt>$stack_root</tt></li> <li>To start the pool, execute <pre>php startsocket.php</pre></li> <li>To stop the sockets, run <pre>php stopsocket.php</pre></li> </ol> Everytime <tt>startsocket</tt> is executed, the file <tt>$stack_root/scripts/maxima/initmaxima.php</tt> is also executed once before the sockets are started. This does the following. <ol> <li>Writes the file <tt>CASkeywords.php</tt> which contains the three arrays, explained in the security section below.</li> <li>Generates the file <tt>maximalocal.mac</tt>, which contains settings from <tt>stackstd.php</tt> in a form suitable for the CAS. For example, what is the gnuplot command? Where should plot files be written to? etc.</li> </ol> <p>To run these scripts in the background, the unix utility <a href="http://www.kuro5hin.org/story/2004/3/9/16838/14935"><tt>screen</tt></a> is useful.</p> --> <h2>Ready to test!</h2> <p>If all the steps above were a success you should be ready to <?php echo "<a href='$stack_web_url'>test the system.</a>"; ?></p> <p>Note, some sample questions are distributed in the file <tt>scripts/install/sample_questions.xml</tt> which you can upload into stack to get you started. You need to <ol> <li>login as the "admin" user, </li> <li>go to the question bank, </li> <li>choose "Upload XML",</li> <li>browse the file system to find the XML file.</li> </ol> <p>No quizzes are created by default at the moment.</p> <h2>Security and Maxima</h2> <p>For the Maxima CAS, the commands are divided into four groups. In the first three cases, the system checks to see if the entries in this list are a substring of anything going to the CAS, and takes the appropriate action.</p> <p>For students' input, or guest input in a CAS chat session (or the like) we operate in a mode which allows only specified strings. For teachers' input, we would like to enable arbitrarily named functions and variables to be present, subject to the naming restrictions of the CAS of course. Hence we basically divide all Maxima commands into the following four groups. <ol> <li><tt>$stack_cas['globalForbid']</tt><br/> Never sent to the CAS. Could also trigger a potential attack warning, although this is not currently implemented.</li> <li><tt>$stack_cas['teacherNotAllow']</tt><br/> These commands have side effects in the Maxima environment, and hence are not allowed. There may be no good reason why a command is here, but there we are. </li> <li><tt>$stack_cas['studentAllow'] </tt><br/> Student's input is divided into strings, and only if all occur in this array is their response processed.</li> <li><tt>The rest</tt></li> </ol> These classifications are given in the file, <tt>maximafun.php</tt>, which you can and should edit. <em>Once you have edited this file, you need to execute the file <tt>initmaxima.php</tt> to re-create <tt>CASkeywords.php</tt>.</em> (This in turn has been generated directly from the Maxima docs using another script, which you need not use). </p> --- NEW FILE: student_forbidden.php --- <a name="forbid"><h2>Forbidden words</h2></a> Suppose that Stack asked you to calculate sin(<font face="SYMBOL">p</font>/4) (for which the answer is of course 2<sup>-1/2</sup>). One cunning plan that might occur to you would be to just enter <tt><font color="GREEN">sin(pi/4)</font></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_options.php --- <?php /** * Describes the data structure stackOption * * @package documentation * @subpackage Stack */ include('en_doc.php'); ?> <h1>Options documentation</h1> <p>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. </p> <p>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.</p> <p>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.</p> <?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>."; } } ?> --- NEW FILE: about_general.php --- <?php /** * A short blurb about what STACK is. * * @package documentation * @subpackage Stack */ ?> <p>The STACK system is a computer aided assessment package for mathematics.</p> <p>In computer aided assessment (CAA), there are two classes of <em>question types</em>. <ul> <li><em>Teacher-provided answer questions</em><br /> In these questions, a student makes a selection from, or interacts with, potential answers which the teacher has selected. Examples include multiple choice, multiple response and so on. </li> <li><em>Student-provided answer questions</em><br /> In these questions the student's answer contains the content. It is not a selection. Examples of these are numeric questions. </li> </ul> STACK concentrates on student-provided answers which are mathematical expressions. For example, a student might respond to a question with a polynomial or matrix. Essantially STACK asks for mathematical expressions and evaluates these using computer algebra. The prototype test is the following pseudo-code. <pre>If simplify(student_answer-teacher_answer) = 0 then mark = 1, else mark = 0. </pre> A CAS provides a library of functions with which to manipulate students' answers and generate outcomes such as providing feedback. Establishing algebraic equivalence with a correct answer is only one kind of manipluation which is possible. Using CAS can also help generate random yet structured problems, and corresponding worked solutions. <p>In STACK a lot of attention has been paid to allowing teachers to author and manage their own questions. You can try this for yourself by looking at the question bank demo, authoring guide and other options available here.</p> <!-- Please do not remove this public credit. CJS, June 2005 --> <p>This system is the brain child of <a href='email:ch...@sa...'>Chris Sangwin</a>.</p> --- NEW FILE: about_develop.php --- <?php /** * Details of how to Develop STACK. * * @package documentation * @subpackage Stack */ ?> <h1>Developing STACK</h1> <p>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> <p>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.</p> <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"><?php ?></font> ... not 'short' tags like <font color="#339900"><? ?></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 /> global </font><font color="#0000BB">$USER</font><font color="#007700">, </font><font color="#0000BB">$CFG</font><font color="#007700">;<br /> <br /> if (</font><font color="#0000BB">$mode</font><font color="#007700">) {<br /> </font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode </font><font color="#007700">= </font><font color="#0000BB">$mode</font><font color="#007700">;<br /> } else if (empty(</font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode</font><font color="#007700">)) {<br /> </font><font color="#0000BB">$USER</font><font color="#007700">-></font><font color="#0000BB">mode </font><font color="#007700">= </font><font color="#0000BB">$CFG</font><font color="#007700">-></font><font color="#0000BB">forum_displaymode</font><font color="#007700">;<br /> }<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">-></font><font color="#0000CC">attempts</font><font color="#006600">) {<br /> if (</font><font color="#0000CC">$numattempts </font><font color="#006600">> </font><font color="#0000CC">$quiz</font><font color="#006600">-></font><font color="#0000CC">attempts</font><font color="#006600">) {<br /> </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">-></font><font color="#CC0000">id"</font><font color="#006600">);<br /> }<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 = "with special characters like a new line \n";<br /> $var = 'a very, very long string with a '.$single.' variable in it';<br /> $var = "some $text with $many variables $within it"; </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 /> </font><font color="#007700">if (!</font><font color="#0000BB">$ratings</font><font color="#007700">) {<br /> </font><font color="#0000BB">$ratings </font><font color="#007700">= array(); </font><font color="#FF8000">// Initialize the empty array</font><font color="#007700"><br /> 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 /> </font><font color="#FF8000">// Process each rating in turn</font><font color="#007700"><br /> 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">=></font><font color="#0000BB"> $thing</font><font color="#007700">)</font><font color="#006600"> {<br /> </font><font color="#007700"> </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"> </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"> </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"> </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> </p> --- NEW FILE: author_questionfields.php --- <?php /** * Describes the data structure stackQuestion * * @package documentation * @subpackage Stack */ include('en_doc.php'); ?> <h1>Question documentation</h1> <p>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> <p>If you would like some examples of how to author questions, please refer to the authoring guide instead.</p> <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!)</p> <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 <em>about</em> 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 <font color=orange><tt>questionBody</tt></font>. 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> <p>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. <p>For example, <font color=orange><tt>questionVarsInst</tt></font> are the <font color=orange><tt>questionVars</tt></font> with their values assigned. <p>Fields in a <tt>stackQuestion</tt> of type <font color=orange><tt>rawkeyvals</tt></font> are <em> not inherited</em> by the </tt>stackQuestionInst</tt>. There is no point storing stings, when we have the parsed, validated <font color=orange><tt>keyvals</tt></font> fields to work with. <?php foreach( $stackQuestionInst as $field => $q_field) { if (array_key_exists('doc',$q_field)) { echo '<br />'.$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 stackQuestionAttempt</h2> This holds data about each student's attempts as a particular <font color=orange><tt>questionInst</tt></font>. 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 <font color=orange><tt>questionInst</tt></font> itself. This field is <?php foreach( $stackQuestionAttempt as $field => $q_field) { echo "<p>Name of field: <font color=orange><tt>$field</tt></font>. Type of field: <font color=orange><tt>$q_field[type]</tt></font>. <br />"; if (array_key_exists('doc',$q_field)) { echo '<br />'.$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) { $fieldname = 'stackQuestion_'.$key; $descript = get_string($fieldname,'stack'); echo "<tr>\n <td>"; echo "<a href=\"javascript:HelpPopup('$key','stackQuestion');\">{$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) { $fieldname = 'stackQuestion_'.$command; $descript = get_string($fieldname,'stack'); } else if ('stackQuestionPotResp' == $stackhelp) { $fieldname = 'stackQuestion_PR_'.$command; $descript = get_string($fieldname,'stack'); } else if ('stackOptions' == $stackhelp) { $fieldname = 'stackOptions_'.$command; $descript = get_string($fieldname,'stack'); } 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> <p>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.</p> <h2>A minimal example</h2> <p>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 >> 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> </p> <p>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> <p>You now have a minimal question working.</p> <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 <em>before</em> 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.</p> <h2>CAS-enabled text: <tt>castext</tt></h2> <p>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 <em>CAS-enabled text</em>. 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.</p> <p><em>Use only simple LaTeX structures, and equations.</em> Only core LaTeX is supported, and experienced users may feel a little disappointed that not all the more complex environments, work. If you do not know how to use LaTeX, some simple examples are given in the <a href="#FAQ">FAQ</a>. </p> <p>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>< html> stuff < 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></p> <h2>Random questions</h2> <p>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 in the documentation for <?php stack_doc_dispstackqfield('questionVarsRaw'); ?> <p>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 <em>p</em>, and used the <em>value</em> of this in the <?php stack_doc_dispstackqfield('questionStem'); ?>. Hence, the user will not see a "<em>p</em>" on the screen when the question is instantiated, but the <em>value</em> of <em>p</em>.</p> <p>Notice also that in the <?php stack_doc_dispstackqfield('questionAns'); ?>, there is a CAS command to differentiate the value of <em>p</em> with respect to <em>x</em>. It is necessary for the CAS to work out the answer in a random question.</p> <p>We are now in a position to generate a random question. Use the data, as follows.</p> <?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); ?> <p>In this new example, we have an extra variable <em>n</em> which is defined to be a random number. This is then used to define the variable <em>p</em> 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.</p> <p>When generating random questions in CAA we talk about <em>random numbers</em> when we really mean <em>pseudo-random numbers</em>. 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. <p>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> <p>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).<br /> <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> <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> <p>Ignore, for now, the <?php stack_doc_dispstackqfield('questionAnsVarsRaw'); ?> field, since we do not need to process the student's answer yet.</p> <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.</p> <p>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.</p> <p><em>DO NOT check the Del box!</em> which would result in this potential response being deleted on the next edit cycle.</p> <p>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.</p> <p>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> <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); ?> <p>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.</p> <p>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.</p> <p>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.</p> <p>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> <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> <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.</p> <?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); ?> <p>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. </p> <h2>Options</h2> <p>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.</p> <p>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>. </p> <p>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. </p> <?php // Examples and documentation for the Question Variables. $descript = get_string('stackQuestion_questionVarsRaw','stack'); echo "<h2><a name=\"qvars_ex\">$descript: Examples</a></h2>\n"; echo $stackQuestion['questionVarsRaw']['doc']; ?> <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></p> <p>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> <p>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... [truncated message content] |
