/readme.html
HTML | 260 lines | 242 code | 18 blank | 0 comment | 0 complexity | 192479b6e26b74bca7a1aef96298c8da MD5 | raw file
- <html>
- <head>
- <title>IMathAS</title>
- <style type="text/css">
- ul li {
- margin-top: .3em;
- }
- ol li {
- margin-top: .3em;
- }
- h1 {
- color: #00f;
- }
- h2,h3,h4 {
- color: #00c;
- }
- </style>
- <body>
- <h1>IMathAS</h1>
- <p>Version: 1.8. Released November 9, 2009 <br/>
- See <a href="changelog.html">Change Log</a> for detailed change history. The most recent version of
- the code is available via SVN at <a href="http://code.google.com/p/imathas/">Google Code</a></p>
-
- <h3>What is IMathAS</h3>
- <p>IMathAS is an Internet Mathematics Assessment System. It is primarily a
- web-based math assessment tool for delivery and automatic grading of math homework
- and tests. Questions are algorithmically generated and numerical and math expression
- answers can be computer graded. Beyond that, IMathAS includes learning management tools,
- including posting of announcements, text files, and attachments, as well as discussion
- forums and a full gradebook. In postings and assessments, IMathAS allows accurate display
- of math and graphs, with simple calculator-style math entry and point-and-click graph
- creation. It is most similar to (and inspired by) <a href="http://webwork.math.rochester.edu/">WebWork</a>
- and <a href="http://wims.unice.fr/">WIMS</a>, and similar to commercial and publisher-produced systems
- like iLrn, MathXL, WebAssign, etc.</p>
-
- <p>IMathAS was written by <a href="http://www.pierce.ctc.edu/dlippman">David Lippman</a> (c) 2006-2009,
- with with partial support from the
- <a href="http://www.sbctc.ctc.edu/College/_g-elchome.aspx">WA State E-Learning Council</a>, the
- <a href="http://www.transitionmathproject.org/">Transition Math Project</a>, and
- <a href="http://www.pierce.ctc.edu">Pierce College</a>. It is distributed under
- the <a href="http://www.gnu.org/copyleft/gpl.html">GPL</a>. See the <a href="license.txt">license.txt</a> file distributed with IMathAS for more details
- and credits for components attributed to others.</p>
-
- <h3>Features</h3>
- <h4>IMathAS was built on three primary philosophies:</h4>
- <ul>
- <li><b>Math</b>: The system was designed for Math assessment; no effort was made for the system to be multi-purpose.</li>
- <li><b>Sharing</b>: The system was setup to encourage sharing of questions within a system and outside. Questions are grouped into
- question libraries, and are not tied directly to a specific assessment. Unless marked Private, questions can be used by
- anyone on the system, or used as a template for writing new questions. Assessments and course setups can be copied
- between users with permission. Export and Import allows the
- sharing of question sets between systems. Also, macro libraries allow for the expansion of IMathAS's question language.
- Users with expertise in a field can develop macro extensions, and share them with other users.</li>
- <li><b>Ease of Install</b>: The system uses standard PHP and MySQL. It requires no special compilation options or installation
- of external programs.</li>
- </ul>
-
- <h4>Core Features include:</h4>
- <ul>
- <li>Display:</li>
- <ul>
- <li>Rich Math and Graph display, using standards-based MathML and SVG, powered
- by Peter Jipsen's <a href="http://www1.chapman.edu/~jipsen/svg/asciisvg.html">ASCIIsvg</a> and
- <a href="http://www1.chapman.edu/~jipsen/mathml/asciimath.html">ASCIIMathML</a>, or using image fallbacks</li>
- <li>Rich Text Editor with built-in Math and Graph support for text items displayed in a course and forum posts</li>
- <li>Alternate display options for screenreaders and browsers without needed support</li>
- </ul>
- <li>Assessment:</li>
- <ul>
- <li>Question types including:</li>
- <ul>
- <li>Functions, with answers like "sin(x)"</li>
- <li>Numbers, compared to a given tolerance</li>
- <li>Calculated Numbers, like 5/3 or 2^5</li>
- <li>Multiple-Choice</li>
- <li>Multiple-Answer</li>
- <li>Matching</li>
- <li>String</li>
- <li>Essay (not computer graded)</li>
- <li>Numerical Matrix</li>
- <li>Calculated Matrix</li>
- <li>Interval</li>
- <li>Calculated Interval</li>
- <li>N-tuples</li>
- <li>Drawing / Graphing</li>
- <li>File Upload</li>
- <li>Multipart</li>
- </ul>
- <li>Multiple display options and assessment settings, including an option for practice sets, and
- due date exceptions for individual students</li>
- <li>Algorithmically generated questions, with a relatively simple-to-use question language
- (loosely based on PHP) with many built-in randomizers and display macros</li>
- <li>Group assessments</li>
- <li>Expandable question language, by installing additional macros</li>
- </ul>
- <li>Other Course Management Features:</li>
- <ul>
- <li>Post text items, uploaded files, or web links to the classroom</li>
- <li>Discussion Forums, optionally gradable </li>
- <li>Full gradebook with support for online and offline grades and flexible grading schemes</li>
- </ul>
- <li>Administration:</li>
- <ul>
- <li>Flexible administration: IMathAS can be centrally administered,
- or teachers can be given rights to create their own courses</li>
- <li>Teachers can be grouped by school or other division, with one or more group administrators</li>
- <li>Courses can have one or more teachers</li>
- </ul>
- <li>Mash-ups:</li>
- <ul>
- <li>Experimental support for <a href="http://www.imsglobal.org/community/forum/categories.cfm?catid=44">BasicLTI</a>, both as a consumer and producer</li>
- <li>Google gadget for listing messages and forum posts</li>
- </ul>
- </ul>
-
- <h4>Details</h4>
- For details on how the system works, look over the <a href="help.html">Help File</a> or view
- <a href="http://www.imathas.com/support.html">training and support</a> resources.
-
- <h3>Why a new system</h3>
- <p>You may be wondering why another system, when excellent systems already exist.</p>
-
- <p>For my purposes, WebWork and WIMS were too difficult to install (since I don't have direct
- access to my school's webserver). I didn't want to use commercial or publisher produced systems
- because I don't want students with used books to incur additional cost.</p>
-
-
- <h3>Installation</h3>
- <p>
- <ol>
- <li>Download IMathAS, extract it, and copy the files to your webserver.</li>
- <li>Alternatively, if you have shell access to your server, enter the directory you want IMathAS in,
- and checkout the code from SVN: <i>svn checkout http://imathas.googlecode.com/svn/trunk/</i>.
- Using SVN greatly simplifies upgrading.</li>
- <li>If your web host requires that you create databases through the web panel, create a database
- and database user for IMathAS now. If you have a username/password with database
- creation priviledges, you can wait and use it later in the install process.</li>
- <li>Open a browser and access install.php. This script will write the config.php file, change directory
- permissions, copy distribution files, and set up the database. At the end of the install you
- will be given the opportunity to install a small set of example questions. <i>Note</i>:
- If you are running on a Windows server, you may need to set directory permissions manually.</li>
- <li>Log into IMathAS. If you didn't change the
- initial imathas user settings when running install.php, log in as 'root' with password 'root'.
- If you did not change the inital imathas user settings, click the "Change Password"
- link now to change the password to something substantial. Alternatively, you can
- go into the Admin page, create a new user with Admin rights, then delete the 'root'
- admin.</li>
- <li>Edit loginpage.php and infoheader.php if desired. If you plan to use the new instructor account
- request page, edit newinstructor.php</li>
- </ol>
- </p>
-
- <h3>Installation Issues/Troubleshooting</h3>
- <p>
- <ul>
- <li>If you receive an 500 access error trying to access install.php, try deleting the .htaccess file in the
- IMathAS root directory. This file is used to give some advice to the web server about file compression
- and file types, but could potentially cause problems depending on the server configuration</li>
- </ul>
- </p>
-
-
- <h3>Upgrading</h3>
- <p>If you are upgrading from IMathAS 1.6 or later, access update.php to install any new database changes
- and learn about any other changes necessary. If you are upgrading from a version earlier
- than 1.6, you'll need to manually apply changes from the upgrade.txt file.
- </p>
-
- <h3>System Requirements</h3>
- <h4>Versions</h4>
- <p>PHP 5 and MySQL 4+ are recommended, and required from some features.
- Most of the system will work with PHP 4.2+
- and MySQL 3.23, but future compatibility is not guaranteed.</p>
- <p>PHP with GD2 and Freetype are recommended for best image-based graph support</p>
-
- <h4>Server Requirements</h4>
- <p>An installation serving 3500+ students
- with 100+ concurrent users has operated well on a commercial shared web server.</p>
-
- <h4>Security</h4>
- <p>IMathAS uses a standard databased-stored sessions-based system. If a user does
- not log out, the session is cleared from database after 24 hours.</p>
-
- <p>Questions (written by teachers) are passed through an interpreter that only allows
- authorized functions to be used. Student answers are evaluated client-side using
- JavaScript, and are never evaled server-side.</p>
-
- <h3>Install Notes</h3>
- <p>
- The install.php script automatically handles the following install steps. They're
- listed here in case anything goes wrong:
- <ul>
- <li>Change permissions (chmod) of the following directories to allow the webserver process
- to write to the directories:
- <ul>
- <li>assessment/libs</li>
- <li>assessment/qimages</li>
- <li>admin/import</li>
- <li>course/files</li>
- <li>filter/graph/imgs</li>
- </ul>
- <br/>
- <i>Note</i>: If you are running on a Windows server, you may need to set directory permissions manually. <br/>
- <i>Note</i>: For security, the admin/import directory should not be web-readable. A .htaccess file is included to
- prevent access. If your server doesn't obey .htaccess files, you may need to do additional tweaking. </li>
- <li>Rename (in the main directory):
- <ul>
- <li>config.php.dist to config.php</li>
- <li>infoheader.php.dist to infoheader.php</li>
- <li>loginpage.php.dist to loginpage.php</li>
- <li>newinstructor.php.dist to newinstructor.php</li>
- </ul></li>
- <li>Edit config.php. Change these options to your liking:</li>
- <ul>
- <li>$dbserver: The address of your database server. Probably www.yoursite.edu or localhost</li>
- <li>$dbname: The name of the IMathAS database</li>
- <li>$dbusername: The username of the IMathAS database user.</li>
- <li>$dbpassword: The password for the IMathAS database user. Choose something really complicated</li>
- <li>$installname: The name of your installation, for personalization.</li>
- <li>$longloginprompt: How you want to prompt new students for a username</li>
- <li>$loginprompt: How you want to prompt students for a username</li>
- <li>$loginformat: Enforce a format requirement on the username</li>
- <li>$emailconfirmation: If set to true, new users will have to respond to an email sent by the system
- before being able to enroll in any classes</li>
- <li>$sendfrom: An email address to send confirmation and notification emails from.</li>
- <li>$imasroot: The web root of the imathas install (ie, http://yoursite.edu $imasroot)</li>
- <li>$mathimgurl: An absolute path or full url to a Mimetex CGI installation, for math image fallback</li>
- <li>$colorshift: Whether icons should change colors as due date approaches. I thought this was cute,
- but others might find it annoying</li>
- <li>$smallheaderlogo: Text or an HTML image tag for a small (120 x 80) logo to display at the top right of
- course pages</li>
- <li>$allownongrouplibs: Whether non-admins should be allowed to create non-group libraries.
- On a single-school install, set to true; for larger installs that plan to
- use the Groups features, set to false</li>
- <li>$allowcourseimport: Whether anyone should be able to import/export questions and libraries from the
- course page. Intended for easy sharing between systems, but the course page
- is cleaner if turned off.</li>
- <li>$allowmacroinstall: Whether admins should be able to install macro files. Macros files hold a large
- security risk, and should only be installed from trusted sources. For a single-admin system, it is
- recommended that you leave this as false, and change it when you need to install a macro</li>
- <li>$sessionpath: change the session file path different than the default.
- This is usually not necessary unless your site is on a server farm, or
- you're on a shared server and want more security of session data</li>
- <li>$mathchaturl: a URL to the live chat server. Leave unchanged to use the local install's
- server. Comment out to disable the chat server. You can also use a different install to
- offload chat on a different server</li>
- <li>$enablebasiclti: Set to true to enable use of IMathAS as a BasicLTI producer.</li>
- <li>$AWSkey,$AWSsecret,$AWSbucket: To allow students and teachers to upload files through
- the text editor, and to enable file upload questions, this specifies an Amazon S3
- key, secret, and bucket to use for file storage. Local storage is not yet implemented.</li>
- </ul>
- <li>Run the dbsetup.php script (access http://yoursite.edu $imasroot/dbsetup.php), or send it
- to your system administrator and ask them to run it, if you don't have creation access
- to the database server. Alternatively, have your system administrator create a database and database user,
- and use these names in the config.php file before running dbsetup.php. This script sets up the necessary database user, database, and tables for IMathAS.</li>
-
- </ul>
- </p>
- </body>
- </html>