Annotation of doc/homework/homework5.html, revision 1.22

1.1       albertel    1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
                      2: <html>
                      3:   <head>
                      4:     <title>LON-CAPA Homework System</title>
                      5:   </head>
                      6: 
1.5       ng          7:   <body bgcolor="white">
1.1       albertel    8:     <h1>LON-CAPA Homework System</h1>
                      9: 
                     10:     <h2>Tags</h2>
                     11:     <ul>
                     12:       <li>
                     13: 	Response tags
                     14: 	<p>
                     15: 	  Arguments for all response tags
                     16: 	</p>
                     17: 	<ul>
                     18: 	  <li>
                     19: 	    <i>ID</i>, if this isn't set it will be set during
                     20: 	    the publication step. It is used to assign parameters names
                     21: 	    in a way that can be tracked if an instructor modifies
                     22: 	    things by hand.
                     23: 	  </li>
                     24: 	  <li>
                     25: 	    <i>name</i> optional, if set, it will be used by the
                     26: 	    resource assembly tool when one is modifying parameters.
                     27: 	    </li>
                     28: 	</ul>
                     29: 	<p>
                     30: 	  Implemented response tags
                     31: 	</p>
                     32: 	<ul>
                     33: 	  <li>
1.2       albertel   34: 	    <b>&lt;responseparam&gt;</b> if it appears it should be
                     35: 	    inside of a &lt;*response&gt; tag, defines an externally
                     36: 	    adjustable parameter for this question. Arguments:
                     37: 	    <ul>
                     38: 	      <li>
                     39: 		<i>default</i> required, specifies a default value for
                     40: 		the parameter
                     41: 	      </li>
                     42: 	      <li>
                     43: 		<i>name</i> required, specifies an internal name for
                     44: 		the parameter
                     45: 	      </li>
                     46: 	      <li>
                     47: 		<i>type</i> required specifies the type of parameter,
                     48: 		one of "tolerance", "int", "float", "string", "date"
                     49: 		(configuration of paramters is handled by
                     50: 		lonparmset.pm and parameter.html)
                     51: 	      </li>
                     52: 	      <li>
                     53: 		<i>description</i> a string describing the parameter,
                     54: 		this is what is used to talk about a parameter outside
                     55: 		of a problem
                     56: 	      </li>
                     57: 	    </ul>
                     58: 	  </li>
                     59: 	  <li>
1.16      albertel   60: 	    <b>&lt;parameter&gt;</b> exactly the same as
                     61: 	    &lt;responseparam&gt; currently, but should not appear
                     62: 	    inside of a &lt;*response&gt;
                     63: 	  </li>
                     64: 	  <li>
1.1       albertel   65: 	    <b>&lt;numericalresponse&gt;</b> implements a numerical
                     66: 	    answer, it needs an internal <b>&lt;textline&gt;</b> for
                     67: 	    the response to go in. It checks all styles of numerical
                     68: 	    supported in CAPA. Possible args are:
                     69: 	    <ul>
1.8       albertel   70: 	      <li><i>answer</i> required, specifies the correct answer, may be either a perl list or scalar</li>
1.1       albertel   71: 	      <li><i>units</i> optional, specifies unit of correct answer, CAPA style</li>
                     72: 	    </ul>
                     73: 	  </li>
                     74: 	  <li>
1.8       albertel   75: 	    <b>&lt;stringresponse&gt;</b> implements a string answer,
                     76: 	    it needs an internal <b>&lt;textline&gt;</b> for the
                     77: 	    response to go in. It can check the string for either case
                     78: 	    or order.
                     79: 	    <ul>
                     80: 	      <li><i>answer</i> required, specifies the correct answer, may be either a perl list or scalar</li>
                     81: 	      <li><i>type</i> optional, CAPA style str args, cs/ci/mc
                     82: 		<ul>
                     83: 		  <li>cs - case senesitive, order important</li>
                     84: 		  <li>ci - case insenesitive, order important</li>
                     85: 		  <li>mc - case insenesitive, order unimportant</li>
                     86: 		</ul>
                     87: 	      </li>
                     88: 	    </ul>
                     89: 	  <li>
1.1       albertel   90: 	    <b>&lt;essayresponse&gt;</b> implements a ungraded large
1.17      albertel   91: 	    text response, it need an internal <b>&lt;textfield&gt;</b>
1.1       albertel   92: 	    for the response to go in.
                     93: 	  </li>
                     94: 	  <li>
                     95: 	    <b>&lt;imageresponse&gt;</b> implements a image click
                     96: 	    style image submission, uses the foil structure tags <a
                     97: 	    href="#foil">below</a>. Additional tags that should appear
                     98: 	    in a &lt;foil&gt; are:
                     99: 	    <ul>
                    100: 	      <li><b>&lt;image&gt;</b> required, the contained text
                    101: 	      specifies a published graphical resource that is the
                    102: 	      image used, should only appear once per foil</li>
                    103: 	      <li><b>&lt;rectangle&gt;</b> required, the contained text
                    104: 	      specifies a rectangular area that is correct, should
                    105: 	      look like (1,2)-(3,4), at least 1 required</li>
                    106: 	      <li><b>&lt;text&gt;</b> required, the contained text is
                    107: 	      printed on top of the image.</li>
                    108: 	    </ul>
                    109: 	  </li>
                    110: 	  <li>
                    111: 	    <b>&lt;optionresponse&gt;</b> implements a "select from
                    112: 	    these choices" style question, the choices are specified
                    113: 	    by the instructor, it uses the foil structure tags <a
                    114: 	    href="#foil">below</a> with this additional args: 
                    115: 	    <ul>
                    116: 	      <li>
                    117: 		<b>&lt;foilgroup&gt;</b> is required to have
                    118: 		<i>options</i> which should be a perl list of possible
                    119: 		options for the student.
                    120: 	      </li>
                    121: 	    </ul>
                    122: 	  </li>
                    123: 	  <li>
                    124: 	    <b>&lt;radiobuttonresponse&gt;</b> implements a true / false
                    125: 	    style question with 1 correct answer.it uses the foil
                    126: 	    structure tags <a href="#foil">below</a> but the
                    127: 	    <i>value</i> of a &lt;foil&gt;can only be "true" or
                    128: 	    "false" or "unused"
                    129: 	  </li>
1.10      albertel  130: 	  <li>
                    131: 	    <b>&lt;dataresponse&gt;</b> implements a straight data
                    132: 	    storage entry idea, needs and interveing input tag like
                    133: 	    &lt;textline&gt; to work correctly.<br>
                    134: 	    Arguments:
                    135: 	    <ul>
                    136: 	      <li>
                    137: 		<i>name</i> internal name for the value, it will have
                    138: 		the part id and respose id added on to it
                    139: 	      </li>
                    140: 	      <li>
                    141: 		<i>type</i> type of data stored in this response
                    142: 		field, should be one of the types supported by
                    143: 		parameter.html
                    144: 	      </li> 
                    145: 	      <li>
                    146: 		<i>display</i> a string that will be used to describe
                    147: 		the field when interfacing with humans
                    148: 	      </li>
                    149: 	    </ul>
1.15      albertel  150: 	  </li>
1.10      albertel  151: 	  <li>
1.15      albertel  152: 	    <p>
                    153: 	      <b>&lt;externalresponse&gt;</b> implements the ability to have
                    154: 	      an external program grade a response, expects either a
                    155: 	      &lt;textline&gt; or &lt;textfield&gt; inside the tag. <br />
                    156: 	    </p>
                    157: 	    Arguments:
                    158: 	    <ul>
                    159: 	      <li>
                    160: 		<i>url</i> the url to submit the answer and form to,
                    161: 		does not need to be a LON-CAPA machine.
                    162: 	      </li>
                    163: 	      <li>
                    164: 		<i>answer</i> a string or scalar variable that can
                    165: 		encode something that should encode the correct
                    166: 		answer, in some cases this may be nothing.
                    167: 	      </li>
                    168: 	      <li>
                    169: 		<i>form</i> a hash variable name that will be
                    170: 		submitted to the remote site as a HTTP form.
                    171: 	      </li>
                    172: 	    </ul>
                    173: 	    <p>
                    174: 	      The response of the remote server needs to be in XML as follows.
                    175: 	    </p>
                    176: 	    <pre>
                    177: &lt;loncapagrade&gt;
                    178:     &lt;awardetail&gt;
                    179: CORRECT
                    180:     &lt;/awardetail&gt;
                    181:     &lt;message&gt;
                    182: A message to be shown to the students
                    183:     &lt;/message&gt;
                    184: &lt;/loncapagrade&gt;
                    185: 	    </pre>
                    186: 	    <ul>
                    187: 	      <li>
                    188: 		<b>&lt;loncapagrade&gt;</b> no arguments but must
                    189: 		surround the response.
                    190: 	      </li>
                    191: 	      <li>
                    192: 		<b>&lt;awardetail&gt;</b> required inner tag, the
                    193: 		response inside must be one of the detailed responses
                    194: 		that appears in the data storage documentation
                    195: 		(CVS:loncapa/doce/homework/datastorage)
                    196: 	      </li>
                    197: 	      <li>
                    198: 		<b>&lt;message&gt;</b> optional message to have shown
                    199: 		to the student
                    200: 	      </li>
                    201: 	    </ul>
                    202: 	  </li>
1.1       albertel  203: 	</ul>
                    204: 	<li>
                    205: 	<a name="foil">Foil Structure Tags</a>
                    206: 	<p>
                    207: 	  All tags that implement a foil structure have an optional
                    208: 	  arg of <i>max</i> that controls the maximum number of total
                    209: 	  foils to show.
                    210: 	</p>
                    211: 	<ul>
                    212: 	  <li>
                    213: 	    <b>&lt;foilgroup&gt;</b> required, must be the tag that
                    214: 	    surrounds all foil definitions	    
                    215: 	  </li>
                    216: 	  <li>
                    217: 	    <b>&lt;foil&gt;</b> required, all data inside is a possible foil
                    218: 	  </li>
                    219: 	  <li>
                    220: 	    <b>&lt;conceptgroup&gt;</b> optional, surrounds a
                    221: 	    collection of &lt;foil&gt;, when a problem is displayed
                    222: 	    only one of the contained &lt;foil&gt;is selected for
                    223: 	    display. It receives one required argument
                    224: 	    <i>concept</i>.
                    225: 	  </li>
                    226: 	</ul>
                    227:       </li>
                    228:       <li>
                    229: 	Hint structure
                    230: 	<p>
                    231: 	  All of these tags must appear inside a <b>&lt;*response&gt;</b> tag.
                    232: 	</p>
                    233: 	<ul>
                    234: 	  <li>
                    235: 	    <b>&lt;hintgroup&gt;</b> Tag that surrounds all of a hint.
                    236: 	  </li>
                    237: 	  <li>
                    238: 	    <b>&lt;hintpart&gt;</b> required, Tag to implement
                    239: 	    conditional hints. It has a required argument
                    240: 	    <i>on</i>. When a &lt;*hint&gt; tag named the same as the
                    241: 	    value the </i>on</i> attribute evaluates to be correct the
                    242: 	    &lt;hintpart&gt; will show. If no other &lt;hintpart&gt;
                    243: 	    are to show then all hintparts with a <i>on</i> of
                    244: 	    "default" will show
                    245: 	  </li>
                    246: 	  <li>
                    247: 	    <b>&lt;numericalhint&gt;</b> has all the arguments that
                    248: 	    &lt;numericalresponse&gt;, does and the required attribute
                    249: 	    <i>name</i> which should be set to the value of which
                    250: 	    &lt;hintpart&gt; will be shown. 
                    251: 	  </li>
1.21      albertel  252: 	  <li>
                    253: 	    <b>&lt;stringhint&gt;</b> has all the arguments that
                    254: 	    &lt;stringresponse&gt;, does and the required attribute
                    255: 	    <i>name</i> which should be set to the value of which
                    256: 	    &lt;hintpart&gt; will be shown. 
                    257: 	  </li>
                    258: 	  <li>
                    259: 	    <b>&lt;formulahint&gt;</b> has all the arguments that
                    260: 	    &lt;formularesponse&gt;, does and the required attribute
                    261: 	    <i>name</i> which should be set to the value of which
                    262: 	    &lt;hintpart&gt; will be shown. 
                    263: 	  </li>
                    264: 	  <li>
                    265: 	    <b>&lt;optionhint&gt;</b> required attribute <i>name</i>
                    266: 	    which should be set to the value of which &lt;hintpart&gt;
                    267: 	    will be shown.
                    268: 	  </li>
                    269: 	  <li>
                    270: 	    <b>&lt;radiobuttonhint&gt;</b> has the required attribute
                    271: 	    <i>name</i> which should be set to the value of which
                    272: 	    &lt;hintpart&gt; will be shown, and <i>answer</i> which
                    273: 	    should be a two element list, frist the type (foil or
                    274: 	    concept) and then either the foil's name or the concept's
                    275: 	    string
                    276: 	  </li>
1.1       albertel  277: 	</ul>
                    278:       </li>
                    279:       <li>
                    280: 	Input Tags
                    281: 	<p>
                    282: 	  This group of tags implement a mechanism for getting data
                    283: 	  for students, they will usually be used by a
                    284: 	  &lt;*response&gt;.
                    285: 	</p>
                    286: 	<ul>
                    287: 	  <li>
1.17      albertel  288: 	    <b>&lt;textfield&gt;</b> creates a Large text input box, If
1.1       albertel  289: 	    data appears between the start and end tags, the data will
1.17      albertel  290: 	    appear in the textfield if the student has not yet made a
1.1       albertel  291: 	    submission. Additionally it takes two arguments <i>rows</i>
                    292: 	    and <i>cols</i> which control the height and width of the
                    293: 	    area respectively. It defaults to 10 and 80.
                    294: 	  </li>
                    295: 	  <li>
                    296: 	    <b>&lt;textline&gt;</b> creates a single line of input
                    297: 	    element, it accepts 1 argument <i>size</i> which controls
                    298: 	    the width on the textline, it defaults to 20.
                    299: 	  </li>
                    300: 	</ul>
                    301:       </li>
                    302:       <li>
                    303: 	Output Tags
                    304: 	<p>
                    305: 	  This group of tags generate useful pieces of output.
                    306: 	</p>
                    307: 	<ul>
                    308: 	  <li>
1.15      albertel  309: 	    <b>&lt;standalone&gt;</b> everything in between the start
                    310: 	    and end tag is shown only on the web, and only if the
                    311: 	    resource is not part of a course.
                    312: 	  </li>
                    313: 	  <li>
1.1       albertel  314: 	    <b>&lt;displayduedate&gt;</b> this will insert the current
                    315: 	    duedate if one is set into the document. It is generated
                    316: 	    to be inside a table of 1x1 elements
                    317: 	  </li>
                    318: 	  <li>
                    319: 	    <b>&lt;displaytitle&gt;</b> this will insert the title of
                    320: 	    the problem from the metadata of the problem
                    321: 	  </li>
                    322: 	  <li>
                    323: 	    <b>&lt;window&gt;</b> the text in between is put in a
                    324: 	    popup javascript window
                    325: 	  </li>
1.12      albertel  326: 	  <li>
                    327: 	    <b>&lt;m&gt;</b> the inside text is LaTeX, and is
                    328: 	    converted to HTML (or MathML) on the fly, if the argument
                    329: 	    <i>eval</i> is set to "on" the intervening text will have
                    330: 	    a perl var expansion done to it before being converted.
                    331: 	  </li>
1.15      albertel  332: 	  <li>
                    333: 	    <b>&lt;randomlabel&gt;</b> shows a specified image with
                    334: 	    images or text labels randomly assigned to a set of
                    335: 	    specific locations, those locations may also have values
                    336: 	    assigned to them. There is a hash generated conating the
                    337: 	    mapping of labels to locations, labels to values, and
                    338: 	    locations to values. Example:
                    339: 	    <pre>
                    340:  &lt;randomlabel bgimg=&quot;URL&quot; width=&quot;12&quot; height=&quot;45&quot; texwidth=&quot;50&quot;&gt;
                    341:     &lt;labelgroup name=&quot;GroupOne&quot; type=&quot;image&quot;&gt;
                    342:       &lt;location x=&quot;123&quot; y=&quot;456&quot; value=&quot;10&quot; /&gt;
                    343:       &lt;location x=&quot;321&quot; y=&quot;654&quot; value=&quot;20&quot; /&gt;
                    344:       &lt;location x=&quot;213&quot; y=&quot;546&quot; value=&quot;13&quot; /&gt;
                    345:       &lt;label description=&quot;TEXT-1&quot;&gt;IMG-URL&lt;/label&gt;
                    346:       &lt;label description=&quot;TEXT-2&quot;&gt;IMG-URL&lt;/label&gt;
                    347:       &lt;label description=&quot;TEXT-3&quot;&gt;IMG-URL&lt;/label&gt;
                    348:     &lt;/labelgroup&gt;
                    349:     &lt;labelgroup name=&quot;GroupTwo&quot; type=&quot;text&quot;&gt;
                    350:       &lt;location x=&quot;12&quot; y=&quot;45&quot; /&gt;
                    351:       &lt;location x=&quot;32&quot; y=&quot;65&quot; /&gt;
                    352:       &lt;location x=&quot;21&quot; y=&quot;54&quot; /&gt;
                    353:       &lt;label&gt;TEXT-1&lt;/label&gt;
                    354:       &lt;label&gt;TEXT-2&lt;/label&gt;
                    355:       &lt;label&gt;TEXT-3&lt;/label&gt;
                    356:     &lt;/labelgroup&gt;
                    357:    &lt;/randomlabel&gt;
                    358: 	    </pre>
                    359: 	    Arguments:
                    360: 	    <ul>
                    361: 	      <li>
                    362: 		<i>bgimg</i> either a fully qualified URL for an
                    363: 		external image, or a loncapa resource, it supports
                    364: 		relative references (../images/apicture.gif), the
                    365: 		image must either be a GIF or JPEG
                    366: 	      </li>
                    367: 	      <li>
                    368: 		<i>width</i> the width of the image in pixels
                    369: 	      </li>
                    370: 	      <li>
                    371: 		<i>height</i> the height of the image in pixels
                    372: 	      </li>
                    373: 	      <li>
                    374: 		<i>texwidth</i> the width of the image in millimeters
                    375: 	      </li>
                    376: 	    </ul>
                    377: 	    Internal tags:
                    378: 	    <ul>
                    379: 	      <li>
                    380: 		<b>&lt;labelgroup&gt;</b> 1 required, multiple
                    381: 		allowed. Declares a group of locations and labels
                    382: 		associated with them.  <br />Arguments:
                    383: 		<ul>
                    384: 		  <li>
                    385: 		    <i>name</i> this is the name of the group, a hash
                    386: 		    with this name will be generated holding the
                    387: 		    mappings for later use in the problem. For each
                    388: 		    location a value will be set for which label is
                    389: 		    there, (EX. $hash{'1'}="TEXT-2"). For locations
                    390: 		    with values the hash will contain 2 items, a
                    391: 		    location to value mapping ($hash{'value_1'}=10),
                    392: 		    and a label to value mapping
                    393: 		    ($hash{'labelvalue_2'}=10). For all image style of
                    394: 		    labels there will also be a label description to
                    395: 		    label URL mapping ($hash{'image_2'}=IMG-URL). Also
                    396: 		    the entry 'numlocations will be set to the total
                    397: 		    number of locations that exist.
                    398: 		    (Note that locations and labels start counting from 1.)
                    399: 		  </li>
                    400: 		  <li>
                    401: 		    <i>type</i> the type of labels in this group,
                    402: 		    either 'image' or 'text'
                    403: 		  </li>
                    404: 		</ul>
                    405: 	      </li>
                    406: 	      <li>
                    407: 		<b>&lt;location&gt;</b> declares a location on the
                    408: 		image that a label should appear at <br />Arguments:
                    409: 		<ul>
                    410: 		  <li>
                    411: 		    <i>x</i> the x value of the location in pixels 
                    412: 		  </li>
                    413: 		  <li>
                    414: 		    <i>y</i> the y value of the location in pixels 
                    415: 		  </li>
                    416: 		  <li>
                    417: 		    <i>value</i> a scalar value to associate at this
                    418: 		    location (optional)
                    419: 		  </li>
                    420: 		</ul>
                    421: 	      </li>
                    422: 	      <li>
                    423: 		<b>&lt;label&gt;</b> declaration of a label, if this
                    424: 		is a text type labelgroup the internal text should be
                    425: 		the text of the label (HTML is not currently
                    426: 		supported), if this is an image type of label the
                    427: 		internal text must be a LON-CAPA resource
                    428: 		specification, and the description filed must be set.
                    429: 		<br />Arguments:
                    430: 		<ul>
                    431: 		  <li>
                    432: 		    <i>description</i> a required field for image
                    433: 		    labels, it will be used when setting values in the
                    434: 		    hash.
                    435: 		  </li>
                    436: 		</ul>
                    437: 	      </li>
                    438: 	    </ul>
                    439: 	  </li>
1.1       albertel  440: 	</ul>
                    441:       </li>
                    442:       <li>
                    443: 	Scripting
1.15      albertel  444:       <p>
                    445: 	These tags allow the document to behave programatically
                    446:       </p>
                    447:       <ul>
                    448: 	<li>
1.1       albertel  449: 	    <b>&lt;display&gt;</b> the intervening perl script is
                    450: 	    evaluated in the safe space and the return value of the
                    451: 	    script replaces the entire tag
                    452: 	  </li>
                    453: 	  <li>
                    454: 	    <b>&lt;import&gt;</b> causes the parse to read in the file
                    455: 	    named in the body of the tag and parse it as if the entire
                    456: 	    text of the file had existed at location of the tag
                    457: 	  </li>
                    458: 	  <li>
                    459: 	    <b>&lt;parserlib&gt;</b> the enclosed filename contains
                    460: 	    definitions for new tags
                    461: 	  </li>
                    462: 	  <li>
                    463: 	    <b>&lt;script&gt;</b> if the argument <i>type</i> is set
                    464: 	    to "loncapa/perl" the enclosed data is a perl script which
                    465: 	    is evaluated inside the perl Safe space. The return value
                    466: 	    of the script is ignored.
                    467: 	  </li>
                    468: 	  <li>
                    469: 	    <b>&lt;scriptlib&gt;</b> the enclosed filename contains
                    470: 	    perl code to run in the safe space
                    471: 	  </li>
                    472: 	  <li>
                    473: 	    <b>&lt;block&gt;</b> has a required argument
                    474: 	    <i>condition</i> that is evaluated, it the condition is
                    475: 	    true everything inside the tag is evaluated, if it is false
                    476: 	    everything inside the block tag is skipped
                    477: 	  </li>
                    478: 	  <li>
                    479: 	    <b>&lt;notsolved&gt;</b> everything inside the tag is
                    480: 	    skipped if the problem is "solved"
                    481: 	  </li>
                    482: 	  <li>
                    483: 	    <b>&lt;postanswerdate&gt;</b> everything inside the tag is
                    484: 	    skipped if the problem is before the answer date
                    485: 	  </li>
                    486: 	  <li>
                    487: 	    <b>&lt;preduedate&gt;</b> everything inside the tag is
                    488: 	    skipped if the problem is after the due date
                    489: 	  </li>
                    490: 	  <li>
                    491: 	    <b>&lt;randomlist&gt;</b> the enclosed tags are parsed in
1.13      albertel  492: 	    a stable random order, optional argument <i>show</i>
                    493: 	    restricts the number of tags indie that are actually
                    494: 	    parsed the no more than <i>show</i>.
1.1       albertel  495: 	  </li>
                    496: 	  <li>
                    497: 	    <b>&lt;solved&gt;</b> everything inside the tag is
                    498: 	    skipped if the problem is "not solved"
                    499: 	  </li>
                    500: 	  <li>
                    501: 	    <b>&lt;while&gt;</b> implements a while loop, required
                    502: 	    argument <i>condition</i> is a perl scriptlet that when
                    503: 	    evaluated results in a true or false value, on true the
                    504: 	    entirety of the text between the whiles is parsed. The
                    505: 	    condition is tested again, etc. If false it goes to the
                    506: 	    next node in the parse.
                    507: 	  </li>
                    508: 	</ul>
                    509:       </li>
                    510:       <li>
                    511: 	Structure Tags
                    512: 	<p>
                    513: 	  These tags give the problem a structure and take care of the
                    514: 	  recording of data and giving the student messages.
                    515: 	</p>
                    516: 	<ul>
                    517: 	  <li>
                    518: 	    <b>&lt;problem&gt;</b> must be the first tag in the file,
                    519: 	    this tag sets up the header of the webpage and generates
                    520: 	    the submit buttons, it also handles due dates properly
                    521: 	  </li>
                    522: 	  <li>
                    523: 	    <b>&lt;part&gt;</b> must be below &lt;problem&gt; if it is
                    524: 	    going to be used. It does many of the same tasks as
                    525: 	    &lt;problem&gt; but allows multiple separate problems to
                    526: 	    exist in a single file.
                    527: 	  </li>
                    528: 	  <li>
                    529: 	    <b>&lt;startouttext&gt;</b><b>&lt;endouttext&gt;</b> these
                    530: 	    tags are somewhat special, they must have no internal text
                    531: 	    and occur in pairs. Their use is to mark up the problem so
                    532: 	    the web editor knows what sections should be edited in a
                    533: 	    plain text block on the web.
                    534: 	  </li>
1.18      albertel  535: 	  <li>
                    536: 	    <b>&lt;comment&gt;</b> Allows one to comment out sections
                    537: 	    of code in a balanced manner, or to provide a comment
                    538: 	    description of how a problem works. Only shows up for the
                    539: 	    edit target, stripped out for all other targets.
                    540: 	  </li>
1.1       albertel  541: 	</ul>
                    542:       </li>
                    543:     </ul>
                    544:     <h2>&lt;script&gt; Functions</h2>
                    545:     <p> 
                    546:       A list of functions that have been written that are available in 
1.5       ng        547:       the Safe space scripting environment inside a problem. 
1.1       albertel  548:     </p>
                    549:     <ul>
1.3       ng        550:       <li>sin(x), cos(x), tan(x)</li>
                    551:       <li>asin(x), acos(x), atan(x), atan2(y,x)</li>
                    552:       <li>log(x), log10(x)</li>
                    553:       <li>exp(), pow(x,y), sqrt(x)</li>
                    554:       <li>abs(x), sgn(x)</li>
                    555:       <li>erf(x), erfc(x)</li>
                    556:       <li>ceil(x), floor(x)</li>
                    557:       <li>min(...), max(...)</li>
                    558:       <li>factorial(n)</li>
                    559:       <li>N%M</li>
                    560:       <li>sinh(x), cosh(x), tanh(x)</li>
                    561:       <li>asinh(x), acosh(x), atanh(x)</li>
                    562:       <li>roundto(x,n)</li>
                    563:       <li>web("a","b","c") or web(a,b,c)</li>
                    564:       <li>html("a") or html(a)</li>
                    565:       <li>j0(x), j1(x), jn(n,x), jv(y,x)</li>
                    566:       <li>y0(x), y1(x), yn(n,x), yv(y,x)</li>
1.1       albertel  567:       <li>random</li>
                    568:       <li>choose</li>
1.3       ng        569:       <li>tex("a","b") or tex(a,b)</li>
                    570:       <li>var_in_tex(a)</li>
                    571:       <li>to_string(x), to_string(x,y)</li>
                    572:       <li>class(), section()</li>
                    573:       <li>name(), student_number()</li>
                    574:       <li>open_date(), due_date(), answer_date()</li>
                    575:       <li>sub_string()</li>
                    576:       <li>array_moments(array)</li>
1.15      albertel  577:       <li>format(x,y),prettyprint(x,y)</li>
1.3       ng        578:       <li>map(...)</li>
1.1       albertel  579:       <li>caparesponse_check</li>
                    580:       <li>caparesponse_check_list</li>
                    581:     </ul>
1.5       ng        582: <!-- Table inserted by H. K. Ng 
                    583:     06/01/2001
                    584:     06/12/2001
                    585: -->
                    586:     <p> 
                    587:       Detailed descriptions of each function and comparison with CAPA.
                    588:     </p>
1.4       ng        589: 
                    590:   <table border=1>
                    591:       <tr>
                    592:             <td valign="top"><b>CAPA Functions</b</td>
                    593:             <td valign="top"><b>LON-CAPA</b</td>
                    594:             <td valign="top"><b>Descriptions</b</td>
                    595:             <td valign="top"><b>Differences (if any)</b</td>
                    596:      </tr>
                    597: 
                    598:     <tr>
                    599:              <td valign="top">sin(x), cos(x), tan(x)</td>
                    600:              <td valign="top">&amp;sin($x), &amp;cos($x), &amp;tan($x)</td>
                    601:              <td valign="top">Trigonometric functions where x is in radians. $x
                    602:          can be a pure number, i.e., you can call &amp;sin(3.1415)</td>
                    603:               <td valign="top">&nbsp</td>
                    604:     </tr>
                    605: 
                    606:     <tr>
                    607:              <td valign="top">asin(x), acos(x), atan(x), atan2(y,x)</td>
                    608:              <td valign="top">&amp;asin($x), &amp;acos($x), &amp;atan($x), &amp;atan2($y,$x)</td>
                    609:              <td valign="top">Inverse trigonometric functions. Return value is
                    610:                  in radians. For asin and acos the value of x must be between -1 and 1.
                    611:                  The atan2 returns a value between -pi and pi the sign of which is determined
                    612:                  by y. $x and $y can be pure numbers</td>
                    613:              <td valign="top">&nbsp;</td>
                    614:     </tr>
                    615: 
                    616:     <tr>
                    617:              <td valign="top">log(x), log10(x)</td>
                    618:              <td valign="top">&amp;log($x), &amp;log10($x)</td>
                    619:              <td valign="top">Natural and base-10 logarithm. $x can be a pure number</td>
                    620:              <td valign="top">&nbsp;</td>
                    621:     </tr>
                    622: 
                    623:     <tr>
                    624:              <td valign="top">exp(x), pow(x,y), sqrt(x)</td>
                    625:              <td valign="top">&amp;exp($x), &amp;pow($x,$y), &amp;sqrt($x)</td>
                    626:              <td valign="top">Exponential, power and square root, i.e.,e<sup>x</sup>, x<sup>y</sup> and /x.                  $x and $y can be pure numbers</td>
                    627: 
                    628:              <td valign="top">&nbsp;</td>
                    629:     </tr>
                    630: 
                    631:     <tr>
                    632:              <td valign="top">abs(x), sgn(x)</td>
                    633:              <td valign="top">&amp;abs($x), &amp;sgn($x)</td>
                    634:              <td valign="top">Abs takes the absolute value of x while sgn(x) returns
                    635:                  1, 0 or -1 depending on the value of x. For x>0, sgn(x) = 1, for x=0, sgn(x)
                    636:                  = 0 and for x&lt;0, sgn(x) = -1. $x can be a pure number</td>
                    637:              <td valign="top">&nbsp;</td>
                    638:     </tr>
                    639: 
                    640:     <tr>
                    641:              <td valign="top">erf(x), erfc(x)</td>
                    642:              <td valign="top">&amp;erf($x), &amp;erfc($x)</td>
                    643:              <td valign="top">Error function.&nbsp; erf = 2/sqrt(pi) integral (0,x) e<sup>t-sq</sup> and <i>                 erfx(x)</i> = 1.0 - <i>erf(x)</i>.&nbsp; $x can be a pure number</td>
                    644:              <td valign="top">&nbsp;</td>
                    645:     </tr>
                    646: 
                    647:     <tr>
                    648:              <td valign="top">ceil(x), floor(x)</td>
                    649:              <td valign="top">&amp;ceil($x), &amp;floor($x)</td>
                    650:              <td valign="top">Ceil function returns an integer rounded up whereas
                    651:                  floor function returns and integer rounded down. If x is an integer than
                    652:                  it returns the value of the integer. $x can be a pure number</td>
                    653:              <td valign="top">&nbsp;</td>
                    654:     </tr>
                    655: 
                    656:     <tr>
                    657:              <td valign="top">min(...), max(...)</td>
                    658:              <td valign="top">&amp;min(...), &amp;max(...)</td>
                    659:              <td valign="top">Returns the minimum/ maximum value of a list of
                    660:                  arguments if the arguments are numbers. If the arguments are strings then
                    661:                  it returns a string sorted according to the ASCII codes</td>
                    662:              <td valign="top">&nbsp;</td>
                    663:     </tr>
                    664: 
                    665:     <tr>
                    666:              <td valign="top">factorial(n)</td>
                    667:              <td valign="top">&amp;factorial($n)</td>
                    668:              <td valign="top">Argument (n) must be an integer else it will round
                    669:                  down. The largest value for n is 170. $n can be a pure number</td>
                    670:              <td valign="top">&nbsp;</td>
                    671:     </tr>
                    672: 
                    673:     <tr>
                    674:              <td valign="top">N%M</td>
                    675:              <td valign="top">$N%$M</td>
                    676: 
                    677:              <td valign="top">N and M are integers and returns the remainder (in
                    678:                  integer) of N/M. $N and $M can be pure numbers</td>
                    679:              <td valign="top">&nbsp;</td>
                    680:     </tr>
                    681: 
                    682:     <tr>
                    683:              <td valign="top">sinh(x), cosh(x), tanh(x)</td>
                    684:              <td valign="top">&amp;sinh($x), &amp;cosh($x), &amp;tanh($x)</td>
                    685:              <td valign="top">Hyperbolic functions. $x can be a pure number</td>
                    686:              <td valign="top">&nbsp;</td>
                    687:     </tr>
                    688: 
                    689:     <tr>
                    690:              <td valign="top">asinh(x), acosh(x), atanh(x)</td>
                    691:              <td valign="top">&amp;asinh($x), &amp;acosh($x), &amp;atanh($x)</td>
                    692:              <td valign="top">Inverse hyperbolic functions. $x can be a pure number</td>
                    693:              <td valign="top">&nbsp;</td>
                    694:     </tr>
                    695: 
                    696:     <tr>
1.9       ng        697:              <td valign="top">/DIS($x,"nn")</td>
                    698:              <td valign="top">&amp;format($x,"nn")</td>
1.19      albertel  699:              <td valign="top">Display or format $x as nn where nn is nF or nE and n is an integer. Also supports the first character being a $, it thjen will format the result with a call to &dollarformat() described below.</td>
1.9       ng        700:              <td valign="top">&nbsp;The difference is obvious.</td>
                    701:     </tr>
                    702: 
                    703:     <tr>
1.15      albertel  704:              <td valign="top">Not in CAPA</td>
                    705:              <td valign="top">&amp;prettyprint($x,"nn")</td>
1.19      albertel  706:              <td valign="top">Display or format $x as nn where nn is nF or nE and n is an integer. Also supports the first character being a $, it then will format the result with a a call to &dollarformat() described below. In E mode it will attempt to generate a pretty x10^3 rather than a E3 following the number</td>
1.15      albertel  707:              <td valign="top">&nbsp;</td>
                    708:     </tr>
                    709: 
                    710:     <tr>
1.19      albertel  711:              <td valign="top">Not in CAPA</td>
                    712:              <td valign="top">&amp;dollarformat($x</td>
                    713:              <td valign="top">Reformats $x to have a $ (or \$ if in tex mode) and to have , grouping thousands.</td>
                    714:              <td valign="top">&nbsp;</td>
                    715:     </tr>
                    716:     <tr>
1.4       ng        717:              <td valign="top">roundto(x,n)</td>
                    718:              <td valign="top">&amp;roundto($x,$n)</td>
                    719:              <td valign="top">Rounds a real number to n decimal points. $x and
                    720:                  $n can be pure numbers</td>
                    721:              <td valign="top">&nbsp;</td>
                    722:     </tr>
                    723: 
                    724:     <tr>
                    725:              <td valign="top">web("a","b","c") or web(a,b,c)</td>
                    726:              <td valign="top">&amp;web("a","b","c") or &amp;web($a,$b,$c)</td>
                    727:              <td valign="top">Returns either a, b or c depending on the output
                    728:                  medium. a is for plain ASCII, b for tex output and c for html output</td>
                    729:              <td valign="top">&nbsp</td>
                    730:     </tr>
                    731: 
                    732:     <tr>
                    733:              <td valign="top">html("a") or html(a)</td>
                    734:              <td valign="top">&amp;html("a") or &amp;html($a)</td>
                    735:              <td valign="top">Output only if the output mode chosen is in html
                    736:                  format</td>
                    737:              <td valign="top">&nbsp;</td>
                    738:     </tr>
                    739: 
                    740:     <tr>
                    741:              <td valign="top">jn(m,x)</td>
                    742:              <td valign="top">&amp;j0($x), &amp;j1($x), &amp;jn($m,$x), &amp;jv($y,$x)</td>
                    743:              <td valign="top">Bessel functions of the first kind with orders 0,
                    744:                  1 and m respectively. For jn(m,x), m must be an integer whereas for jv(y,x),
                    745:                  y is real. $x can be a pure number. $m must be an integer and can be a
                    746:                  pure integer number. $y can be a pure real number</td>
                    747:              <td valign="top">In CAPA, j0, j1 and jn are contained in one function,
1.5       ng        748:                  jn(m,x) where m takes the value of 0, 1 or 2. jv(y,x) is new to LON-CAPA.</td>
1.4       ng        749:     </tr>
                    750: 
                    751:     <tr>
                    752:              <td valign="top">yn(m,x)</td>
                    753:              <td valign="top">&amp;y0($x), &amp;y1($x), &amp;yn($m,$x), &amp;yv($y,$x)</td>
                    754:              <td valign="top">Bessel functions of the second kind with orders
                    755:                  0, 1 and m respectively. For yn(m,x), m must be an integer whereas for
                    756:                  yv(y,x), y is real. $x can be a pure number. $m must be an integer and
                    757:                  can be a pure integer number. $y can be a pure real number</td>
                    758:              <td valign="top">In CAPA, y0, y1 and yn are contained in one function,
1.5       ng        759:                  yn(m,x) where m takes the value of 0, 1 or 2. yv(y,x) is new to LON-CAPA.</td>
1.4       ng        760:     </tr>
                    761: 
                    762:     <tr>
                    763:              <td valign="top">random(l,u,d)</td>
                    764:              <td valign="top">&amp;random($l,$u,$d)</td>
                    765:              <td valign="top">Returns a uniformly distributed random number between
                    766:                  the lower bound, l and upper bound, u in steps of d. $l, $u and $d can
                    767:                  be pure numbers</td>
                    768:              <td valign="top">In CAPA, all the 3 arguments must be of the same
                    769:                  type. However, now you can mix the type</td>
                    770:     </tr>
                    771: 
                    772:     <tr>
                    773:              <td valign="top">choose(i,...)</td>
                    774:              <td valign="top">&amp;choose($i,...)</td>
                    775:              <td valign="top">Choose the ith item from the argument list. i must
                    776:                  be an integer greater than 0 and the value of i should not exceed the number
                    777:                  of items. $i can be a pure integer</td>
                    778:              <td valign="top">&nbsp;</td>
                    779:     </tr>
                    780: 
                    781:     <tr>
1.11      albertel  782:              <td valign="top">/MAP(seed;w,x,y,z;a,b,c,d)</td>
1.7       ng        783:              <td valign="top">Option 1 - &amp;map($seed,[\$w,\$x,\$y,\$z],[$a,$b,$c,$d]) or <br> 
                    784:                   Option 2 - &amp;map($seed,\@mappedArray,[$a,$b,$c,$d]) <br>
                    785:                   Option 3 - @mappedArray = &amp;map($seed,[$a,$b,$c,$d]) <br>
                    786:                   Option 4 - ($w,$x,$y,$z) = &amp;map($seed,\@a) <br>
                    787:                   where $a='A'<br>
                    788:                         $b='B'<br>
                    789:                         $c='B'<br>
                    790:                         $d='B'<br>
                    791:                         $w, $x, $y, and $z are variables</td>
1.6       ng        792:              <td valign="top">Assigns to the variables $w, $x, $y and $z the values of the
1.7       ng        793:                   $a, $b, $c and $c (A, B, C and D). The precise value for $w .. depends
                    794:                   on the seed. (Option 1 of calling map). 
                    795:                   In option 2, the values of $a, $b .. are mapped into the array, @mappedArray. The two
                    796:                   options illustrate the different grouping. Options 3 and 4 give a consistent 
                    797:                   way (with other functions) of mapping the items. For each option, the group can
                    798:                   be passed as an array, for example, [$a,$b,$c,$d] => \@a.</td>
1.6       ng        799:              <td valign="top">In CAPA, the arguments are divided into three groups separated
                    800:                   by a semicolon ;. In LON-CAPA, the separation is done by using [] brackets or
                    801:                   using an array @a. Note the backslash (\) before the arguments in the
                    802:                   second and third groups.</td>
                    803:     </tr>
                    804: 
                    805: 
                    806:     <tr>
                    807:              <td valign="top">rmap(seed;a,b,c,d;w,x,y,z)</td>
1.7       ng        808:              <td valign="top">Option 1 - &amp;rmap($seed,[\$w,\$x,\$y,\$z],[$a,$b,$c,$d]) or <br> 
                    809:                   Option 2 - &amp;rmap($seed,\@rmappedArray,[$a,$b,$c,$d]) <br>
                    810:                   Option 3 - @rmapped_array = &amp;rmap($seed,[$a,$b,$c,$d]) <br>
                    811:                   Option 4 - ($w,$x,$y,$z) = &amp;rmap($seed,\@a) <br>
                    812:                   where $a='A'<br>
                    813:                         $b='B'<br>
                    814:                         $c='B'<br>
                    815:                         $d='B'<br>
                    816:                         $w, $x, $y, and $z are variables</td>
1.6       ng        817:              <td valign="top">The rmap functions does the reverse action of map if the same seed
                    818:                   is used in calling map and rmap. </td>
1.11      albertel  819:              <td valign="top">In CAPA, the arguments are divided into
                    820:              three groups separated by a semicolon ;. In LON-CAPA, the
                    821:              separation is done by using [] brackets (with create an
                    822:              unamed vector reference) or using an array @a. Note the
                    823:              backslash (\) before the arguments in the second and
                    824:              third groups (Which cause Perl to send to variable
                    825:              locations rather than the variable values, similar to a C
                    826:              pointer).</td>
1.6       ng        827:     </tr>
1.8       albertel  828:       
                    829:      <tr>
                    830:              <td valign="top">NOT IMPLEMENTED IN CAPA</td>
                    831:              <td valign="top">$a=&amp;xmlparse($string) </td>
                    832:              <td valign="top">Runs the internal parser over the
                    833: 	  argument parsing for display. <b>Warning</b> This will
                    834: 	  result in different strings in different targets. Don't use
                    835: 	  the results of this function as an answer.</td>
                    836:              <td valign="top">New to LON-CAPA</td>
                    837:     </tr>
1.6       ng        838: 
                    839:     <tr>
1.4       ng        840:              <td valign="top">tex(a,b), tex("a","b")</td>
                    841:              <td valign="top">&amp;tex($a,$b), &amp;tex("a","b")</td>
                    842:              <td valign="top">Returns a if the output mode is in tex otherwise
                    843:                   returns b</td>
                    844:              <td valign="top">&nbsp;</td>
                    845:     </tr>
                    846: 
                    847:     <tr>
                    848:              <td valign="top">var_in_tex(a)</td>
                    849:              <td valign="top">&amp;var_in_tex($a)</td>
                    850:              <td valign="top">Equivalent to tex("a","")</td>
                    851:              <td valign="top">&nbsp;</td>
                    852:     </tr>
                    853: 
                    854:     <tr>
                    855:              <td valign="top">to_string(x), to_string(x,y)</td>
                    856:              <td valign="top">&amp;to_string($x), &amp;to_string($x,$y)</td>
                    857:              <td valign="top">If x is an integer, returns a string. If x is real
                    858:                 than the output is a string with format given by y. For example, if x =
                    859:                 12.3456, &amp;to_string(x,".3F") = 12.345 and &amp;to_string(x,".3E") =
                    860:                 1.234E+01.</td>
                    861:              <td valign="top">&nbsp;</td>
                    862:     </tr>
                    863: 
                    864:     <tr>
                    865:              <td valign="top">capa_id(), class(), section(), set(), problem()</td>
                    866:              <td valign="top">&amp;class(), &amp;section()</td>
                    867:              <td valign="top">Returns null string, class descriptive name, section
                    868:                     number, set number and null string.</td>
                    869:              <td valign="top">capa_id(), set() and problem() are no longer used.
                    870:                     Currently, they return a null value.</td>
                    871:     </tr>
                    872: 
                    873:     <tr>
                    874:              <td valign="top">name(), student_number()</td>
                    875:              <td valign="top">&amp;name(), &amp;student_number()</td>
                    876:              <td valign="top">Return the full name in the following format: lastname,
                    877:                     firstname initial. Student_number returns the student 9-alphanumeric string.
                    878:                     If undefined, the functions return null.</td>
                    879:              <td valign="top">&nbsp;</td>
                    880:     </tr>
                    881: 
                    882:     <tr>
                    883:              <td valign="top">open_date(), due_date(), answer_date()</td>
                    884:              <td valign="top">&amp;open_date(), &amp;due_date(), &amp;answer_date()</td>
                    885:              <td valign="top">Problem open date, due date and answer date. The
                    886:                     time is also included in 24-hr format.</td>
                    887:              <td valign="top">Output format for time is changed slightly. If pass
                    888:                     noon, it displays ..pm else it displays ..am. So 23:59 is displayed as
                    889:                     11:59 pm.</td>
                    890:     </tr>
                    891: 
                    892:     <tr>
                    893:              <td valign="top">get_seed(), set_seed()</td>
                    894:              <td valign="top">Not implemented</td>
                    895:              <td valign="top">Get and set the random seed.</td>
                    896:              <td valign="top">&nbsp;</td>
                    897:     </tr>
                    898: 
                    899:     <tr>
                    900:              <td valign="top">sub_string(a,b,c)</td>
                    901:              <td valign="top">&amp;sub_string($a,$b,$c) <br>perl&nbsp; substr function. 
                    902:                  However, note the differences</td>
                    903:              <td valign="top">Retrieve a portion of string a starting from b and
                    904:                     length c. For example,&nbsp; $a = "Welcome to LON-CAPA"; 
                    905:                     $result=&amp;sub_string($a,4,4); then $result is "come"</td>
                    906:              <td valign="top">Perl intrinsic function, substr(string,b,c) starts
                    907:                     counting from 0 (as opposed to 1). In the example to the left, substr($a,4,4)
                    908:                     returns "ome ".</td>
                    909:     </tr>
                    910: 
                    911:     <tr>
                    912:              <td valign="top">array[xx]</td>
                    913:              <td valign="top">@arrayname <br>Array is intrinsic in perl. 
                    914:                  To access a specific element use $arrayname[$n] where $n 
                    915:                  is the $n+1 element since the array count starts from 0</td>
                    916:              <td valign="top">"xx" can be a variable or a calculation.</td>
                    917:              <td valign="top">In LON-CAPA, an array is defined by @arrayname.
                    918:                   It is not necessary to specify the dimension of the array.&nbsp;</td>
                    919:     </tr>
                    920: 
                    921:     <tr>
                    922:              <td valign="top">array_moments(B,A)</td>
                    923:              <td valign="top">@B=&amp;array_moments(@A)</td>
                    924:              <td valign="top">Evaluates the moments of an array A and place the
                    925:                   result in array B[i] where i = 0 to 4. The contents of B are as follows:
                    926:                   B[0] = number of elements, B[1] = mean, B[2] = variance, B[3] = skewness
                    927:                   and B[4] = kurtosis.</td>
1.5       ng        928:              <td valign="top">In CAPA, the moments are passed as an array in the first argument whereas
                    929:                   in LON-CAPA, the array containing the moments are set equal to the function.</td>
1.4       ng        930:     </tr>
                    931: 
                    932:     <tr>
                    933:              <td valign="top">array_max(Name), array_min(Name)</td>
                    934:              <td valign="top">&amp;min(@Name), &amp;max(@Name)</td>
                    935:              <td valign="top">In LON-CAPA to find the maximum value of an array, use
                    936:                    &amp;max(@arrayname)&nbsp; and to find the minimum value of an array, use
                    937:                    &amp;min(@arrayname)</td>
                    938:              <td valign="top">Combined with the min and max functions defined
                    939:                 earlier.</td>
                    940:     </tr>
                    941: 
                    942:     <tr>
                    943:              <td valign="top">init_array(Name)</td>
                    944:              <td valign="top">undef @name</td>
                    945:              <td valign="top">To destroy the contents of an array, use</td>
                    946:              <td valign="top">Use perl intrinsic undef function.</td>
                    947:     </tr>
1.5       ng        948:      <tr>
                    949:              <td valign="top">random_normal (return_array,item_cnt,seed,av,std_dev)</td>
                    950:              <td valign="top">@return_array=&random_normal ($item_cnt,$seed,$av,$std_dev)</td>
                    951:              <td valign="top">Generate $item_cnt deviates of normal distribution of average $av and
                    952:                         standard deviation $std_dev. The distribution is generated from seed $seed</td>
                    953:              <td valign="top">In CAPA the results are passed as the first argument whereas in LON-CAPA 
                    954:                         the results are set equal to the function.</td>
                    955:     </tr>
                    956:      <tr>
                    957:              <td valign="top">random_beta (return_array,item_cnt,seed,aa,bb)</td>
                    958:              <td valign="top">@return_array=&random_beta ($item_cnt,$seed,$aa,$bb) <br>
                    959:                         NOTE: Both $aa and $bb MUST be greater than 1.0E-37.</td>
                    960:              <td valign="top">Generate $item_cnt deviates of beta distribution. 
                    961:                         The density of beta is:
                    962:                         X^($aa-1) *(1-X)^($bb-1) /B($aa,$bb) for 0&lt;X&lt;1.</td>
                    963:              <td valign="top">In CAPA the results are passed as the first argument whereas in LON-CAPA 
                    964:                         the results are set equal to the function.</td>
                    965:     </tr>
                    966:      <tr>
                    967:              <td valign="top">random_gamma (return_array,item_cnt,seed,a,r)</td>
                    968:              <td valign="top">@return_array=&random_gamma ($item_cnt,$seed,$a,$r) <br>
                    969:                         NOTE: Both $a and $r MUST be positive.</td>
                    970:              <td valign="top">Generate $item_cnt deviates of gamma distribution. 
                    971:                         The density of gamma is:
                    972:                         ($a**$r)/gamma($r) * X**($r-1) * exp(-$a*X).</td>
                    973:              <td valign="top">In CAPA the results are passed as the first argument whereas in LON-CAPA 
                    974:                         the results are set equal to the function.</td>
                    975:     </tr>
                    976:      <tr>
                    977:              <td valign="top">random_exponential (return_array,item_cnt,seed,av)</td>
                    978:              <td valign="top">@return_array=&random_exponential ($item_cnt,$seed,$av) <br>
                    979:                         NOTE: $av MUST be non-negative.</td>
                    980:              <td valign="top">Generate $item_cnt deviates of exponential distribution. </td>
                    981:              <td valign="top">In CAPA the results are passed as the first argument whereas in LON-CAPA 
                    982:                         the results are set equal to the function.</td>
                    983:     </tr>
                    984:      <tr>
                    985:              <td valign="top">random_poisson (return_array,item_cnt,seed,mu)</td>
                    986:              <td valign="top">@return_array=&random_poisson ($item_cnt,$seed,$mu) <br>
                    987:                         NOTE: $mu MUST be non-negative.</td>
                    988:              <td valign="top">Generate $item_cnt deviates of poisson distribution. </td>
                    989:              <td valign="top">In CAPA the results are passed as the first argument whereas in LON-CAPA 
                    990:                         the results are set equal to the function.</td>
                    991:     </tr>
                    992:      <tr>
                    993:              <td valign="top">random_chi (return_array,item_cnt,seed,df)</td>
                    994:              <td valign="top">@return_array=&random_chi ($item_cnt,$seed,$df) <br>
                    995:                         NOTE: $df MUST be positive.</td>
                    996:              <td valign="top">Generate $item_cnt deviates of chi_square distribution with $df 
                    997:                         degrees of freedom. </td>
                    998:              <td valign="top">In CAPA the results are passed as the first argument whereas in LON-CAPA 
                    999:                         the results are set equal to the function.</td>
                   1000:     </tr>
                   1001:      <tr>
                   1002:              <td valign="top">random_noncentral_chi (return_array,item_cnt,seed,df,nonc)</td>
                   1003:              <td valign="top">@return_array=&random_noncentral_chi ($item_cnt,$seed,$df,$nonc) <br>
                   1004:                         NOTE: $df MUST be at least 1 and $nonc MUST be non-negative.</td>
                   1005:              <td valign="top">Generate $item_cnt deviates of noncentral_chi_square 
                   1006:                         distribution with $df 
                   1007:                         degrees of freedom and noncentrality parameter $nonc. </td>
                   1008:              <td valign="top">In CAPA the results are passed as the first argument whereas in LON-CAPA 
                   1009:                         the results are set equal to the function.</td>
                   1010:     </tr>
                   1011:      <tr>
                   1012:              <td valign="top">NOT IMPLEMENTED IN CAPA</td>
                   1013:              <td valign="top">@return_array=&random_f ($item_cnt,$seed,$dfn,$dfd) <br>
                   1014:                         NOTE: Both $dfn and $dfd MUST be positive.</td>
                   1015:              <td valign="top">Generate $item_cnt deviates of F (variance ratio) distribution with  
                   1016:                         degrees of freedom $dfn (numerator) and $dfd (denominator). </td>
                   1017:              <td valign="top">New to LON-CAPA</td>
                   1018:     </tr>
                   1019:      <tr>
                   1020:              <td valign="top">NOT IMPLEMENTED IN CAPA</td>
                   1021:              <td valign="top">@return_array=&random_noncentral_f ($item_cnt,$seed,$dfn,$dfd,$nonc) <br>
                   1022:                         NOTE: $dfn must be at least 1, $dfd MUST be positive, and $nonc must
                   1023:                         be non-negative.</td>
                   1024:              <td valign="top">Generate $item_cnt deviates of noncentral F (variance ratio) 
                   1025:                         distribution with degrees of freedom $dfn (numerator) and $dfd (denominator).
                   1026:                         $nonc is the noncentrality parameter. </td>
                   1027:              <td valign="top">New to LON-CAPA</td>
                   1028:     </tr>
                   1029:      <tr>
1.9       ng       1030:              <td valign="top">NOT DOCUMENTED IN CAPA</td>
                   1031:              <td valign="top">@return_array=&random_multivariate_normal ($item_cnt,$seed,\@mean,\@covar) <br>
                   1032:                         NOTE: @mean should be of length p array of real numbers. @covar should be a length
                   1033:                         p array of references to length p arrays of real numbers (i.e. a p by p matrix.</td>
1.5       ng       1034:              <td valign="top">Generate $item_cnt deviates of multivariate_normal distribution with  
                   1035:                         mean vector @mean and variance-covariance matrix. </td>
1.9       ng       1036:              <td valign="top">Note the backslash before the @mean and @covar arrays.</td>
1.5       ng       1037:     </tr>
                   1038:      <tr>
                   1039:              <td valign="top">NOT IMPLEMENTED IN CAPA</td>
                   1040:              <td valign="top">@return_array=&random_multinomial ($item_cnt,$seed,@p) <br>
                   1041:                         NOTE: $item_cnt is rounded with int() and the result must be non-negative. 
                   1042:                         The number of elements in @p must be at least 2.</td>
                   1043:              <td valign="top">Returns single observation from multinomial distribution with  
                   1044:                         $item_cnt events classified into as many categories as the length of @p.
                   1045:                         The probability of an event being classified into category i is given by 
                   1046:                         ith element of @p. The observation is an array with length equal to @p, so
                   1047:                         when called in a scalar context it returns the length of @p. The sum of the
                   1048:                         elements of the obervation is equal to $item_cnt.</td>
                   1049:              <td valign="top">New to LON-CAPA</td>
                   1050:     </tr>
                   1051:      <tr>
                   1052:              <td valign="top">NOT IMPLEMENTED IN CAPA</td>
1.20      albertel 1053:              <td valign="top">@return_array=&random_permutation ($seed,@array) </td>
1.5       ng       1054:              <td valign="top">Returns @array randomly permuted.</td>
                   1055:              <td valign="top">New to LON-CAPA</td>
                   1056:     </tr>
                   1057:      <tr>
                   1058:              <td valign="top">NOT IMPLEMENTED IN CAPA</td>
                   1059:              <td valign="top">@return_array=&random_uniform ($item_cnt,$seed,$low,$high) <br>
                   1060:                         NOTE: $low must be less than or equal to $high.</td>
                   1061:              <td valign="top">Generate $item_cnt deviates from a uniform distribution. </td>
                   1062:              <td valign="top">New to LON-CAPA</td>
                   1063:     </tr>
                   1064:      <tr>
                   1065:              <td valign="top">NOT IMPLEMENTED IN CAPA</td>
                   1066:              <td valign="top">@return_array=&random_uniform_integer ($item_cnt,$seed,$low,$high) <br>
                   1067:                         NOTE: $low and $high are both passed through int().
                   1068:                               $low must be less than or equal to $high.</td>
                   1069:              <td valign="top">Generate $item_cnt deviates from a uniform distribution in integers. </td>
                   1070:              <td valign="top">New to LON-CAPA</td>
                   1071:     </tr>
                   1072:      <tr>
                   1073:              <td valign="top">NOT IMPLEMENTED IN CAPA</td>
                   1074:              <td valign="top">@return_array=&random_binomial ($item_cnt,$seed,$nt,$p) <br>
                   1075:                         NOTE: $nt is rounded using int() and the result must be non-negative. 
                   1076:                               $p must be between 0 and 1 inclusive.</td>
                   1077:              <td valign="top">Generate $item_cnt deviates from the binomial distribution with
                   1078:                         $nt trials and the probabilty of an event in each trial is $p. </td>
                   1079:              <td valign="top">New to LON-CAPA</td>
                   1080:     </tr>
                   1081:      <tr>
                   1082:              <td valign="top">NOT IMPLEMENTED IN CAPA</td>
                   1083:              <td valign="top">@return_array=&random_negative_binomial ($item_cnt,$seed,$ne,$p) <br>
                   1084:                         NOTE: $ne is rounded using int() and the result must be positive. 
                   1085:                               $p must be between 0 and 1 exclusive.</td>
                   1086:              <td valign="top">Generate an array of $item_cnt outcomes generated from 
                   1087:                         negative binomial distribution with
                   1088:                         $ne events and the probabilty of an event in each trial is $p. </td>
                   1089:              <td valign="top">New to LON-CAPA</td>
1.4       ng       1090:     </tr>
1.5       ng       1091:  </table>
1.22    ! albertel 1092:     <p>
        !          1093:       We also support these functions from Math::Cephes
        !          1094: <pre>
        !          1095:  bdtr:  Binomial distribution
        !          1096:  bdtrc:  Complemented binomial distribution
        !          1097:  bdtri:  Inverse binomial distribution
        !          1098:  btdtr:  Beta distribution
        !          1099:  chdtr:  Chi-square distribution
        !          1100:  chdtrc:  Complemented Chi-square distribution
        !          1101:  chdtri:  Inverse of complemented Chi-square distribution
        !          1102:  fdtr:  F distribution
        !          1103:  fdtrc:  Complemented F distribution
        !          1104:  fdtri:  Inverse of complemented F distribution
        !          1105:  gdtr:  Gamma distribution function
        !          1106:  gdtrc:  Complemented gamma distribution function
        !          1107:  nbdtr:  Negative binomial distribution
        !          1108:  nbdtrc:  Complemented negative binomial distribution
        !          1109:  nbdtri:  Functional inverse of negative binomial distribution
        !          1110:  ndtr:  Normal distribution function
        !          1111:  ndtri:  Inverse of Normal distribution function
        !          1112:  pdtr:  Poisson distribution
        !          1113:  pdtrc:  Complemented poisson distribution
        !          1114:  pdtri:  Inverse Poisson distribution
        !          1115:  stdtr:  Student's t distribution
        !          1116:  stdtri:  Functional inverse of Student's t distribution
        !          1117: </pre>
        !          1118: Plase see <a href="http://search.cpan.org/author/RKOBES/Math-Cephes-0.36/lib/Math/Cephes.pod">Math::Cephes</a> for more information
        !          1119: 
        !          1120:     </p>
1.5       ng       1121: <!-- insertion ends -->
1.4       ng       1122: 
1.1       albertel 1123:     <h2>&lt;script&gt; Variables</h2>
                   1124:     <ul>
                   1125:       <li>
                   1126: 	$external::target - set to the current target the xml parser
                   1127: 	is parsing for
                   1128:       </li>
                   1129:       <li>
                   1130: 	$external::part - set to the <i>id</i> of the current problem
1.14      albertel 1131: 	&lt;part&gt;; zero if there are no &lt;part&gt;
1.1       albertel 1132:       </li>
                   1133:       <li>
                   1134: 	$external::gradestatus - set to the value of the current
                   1135: 	resource.partid.solved value
                   1136:       </li>
                   1137:       <li>
                   1138: 	$external::datestatus - set to the current status of the clock
1.14      albertel 1139: 	either CLOSED, CAN_ANSWER, CANNOT_ANSWER, SHOW_ANSWER, or UNCHECKEDOUT
1.1       albertel 1140:       </li>
                   1141:       <li>
                   1142: 	$external::randomseed - set to the number that was used to
                   1143: 	seed the random number generator
                   1144:       </li>
                   1145:       <li>$pi - set to PI </li>
1.3       ng       1146:       <li>$rad2deg - converts radians to degrees </li>
                   1147:       <li>$deg2rad - converts degrees to radians </li>
1.1       albertel 1148:     </ul>
1.14      albertel 1149: 
                   1150:     <h2> Form internals </h2>
                   1151:     <p> Form elements used for homework editing/response </p>
                   1152:     <p> the form is named lonhomework </p>
                   1153:     <h3> Viewing a problem (either CSTR or RES space)</h3>
                   1154:     <ul>
                   1155:       <li>
                   1156: 	grade_target, grade_username, grade_domain, grade_symb - the
                   1157: 	vaules take precedence over the the normal ENV settings of
                   1158: 	these, use &Apache::lonxml::whichuser() to get back the
                   1159: 	correct vaues of the items
                   1160:       </li>
                   1161:       <li>
                   1162: 	HWVAL_response:number - the name of the input elements for each response. The response is the response's ID, and the :number part exists only for response with multiple foils, and is a unique number in order of the submission
                   1163:       </li>
                   1164:       <li>
                   1165: 	changerandseed - the 'Change' button, only exists right after
                   1166: 	the Change button is clicked
                   1167:       </li>
                   1168:       <li>
                   1169: 	problemmode - in CSTR, it is either 'View','Edit','EditXML' or
                   1170: 	'Analyze' depending on the desired view
                   1171:       </li>
                   1172:       <li>
                   1173: 	rndseed - the currently requested random seed
                   1174:       </li>
                   1175:       <li>
                   1176: 	showallfoils - if it exists, and we are in CSTR space, the
                   1177: 	problem should ignore &lt;conceptgroup&gt; and the response's
                   1178: 	max setting and show all possible foils
                   1179:       </li>
                   1180:       <li>
                   1181: 	submit - the name of the Submit button
                   1182:       </li>
                   1183:       <li>
                   1184: 	submitted - a hidden form parameter that can be used to tell
                   1185: 	if the student has submitted answers or not, if it is set,
                   1186: 	there should be answers to grade.
                   1187:       </li>
                   1188:     </ul>
                   1189:     <h3> Editing a problem (Edit mode)</h3>
                   1190:     <p> tagdepth referes to the current value of the xmlparsers tagdepth couter ($Apache::lonxml::currentdepth)</p>
                   1191: <p> Note: the file edit.pm has many helper functions for creating the standard elements for editing a tag and it's attributes, all of those functions follow these conventions </p>
                   1192:     <ul>
                   1193:       <li>
                   1194: 	tagdepth_argname - I.E. 1_3.max, a parameter editing value,
                   1195: 	max is the name of the parameter and it is for the third tag
                   1196: 	inside the first tag
                   1197:       </li>
                   1198:       <li>
                   1199: 	delete_tagdepth - if set to yes, delete tag tagdepth and all
                   1200: 	tags inside of it
                   1201:       </li>
                   1202:       <li>
                   1203: 	homework_edit_tagdepth - used by both &Apache::edit::editline
                   1204: 	and &Apache::edit::editfield for the &lt;textarea&gt; and
                   1205: 	&lt;input&gt; form elements they create
                   1206:       </li>
                   1207:       <li>
                   1208: 	insert_tagdepth - used to request an tag insert, it is set to
                   1209: 	the id number of the requested tag in the
                   1210: 	%Apache::lonxml::insertlist
                   1211:     </ul>
1.1       albertel 1212:     <hr>
                   1213:     <address><a href="mailto:albertel@marvin.lite.msu.edu">Guy Albertelli</a></address>
                   1214: <!-- Created: Thu May 17 15:05:35 EDT 2001 -->
                   1215: <!-- hhmts start -->
1.22    ! albertel 1216: Last modified: Wed Nov 13 17:33:43 EST 2002
1.1       albertel 1217: <!-- hhmts end -->
                   1218:   </body>
                   1219: </html>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>