--- modules/damieng/clean_xml/loncapa.xsd	2015/04/17 15:35:01	1.1
+++ modules/damieng/clean_xml/loncapa.xsd	2015/04/27 20:39:01	1.3
@@ -791,7 +791,11 @@
   </xs:complexType>
   <xs:complexType name="optionresponse--drawoptionlist">
     <xs:annotation>
-      <xs:documentation>Draw Option List</xs:documentation>
+      <xs:documentation>
+        Draw Option List
+        
+        By default, the list of options is presented in front of the foils. Using the optional &lt;drawoptionlist&gt; element, the list of options can be embedded into a foil.
+      </xs:documentation>
     </xs:annotation>
   </xs:complexType>
   
@@ -804,6 +808,7 @@
     <xs:annotation>
       <xs:documentation>
         Query for matches betweens items from two lists.
+        It is also possible to query for matches with optionresponse, but optionresponse only accepts simple text for the matches. With matchresponse, it is possible to use anything as a match, such as equations, images, plots, or long styled texts.
       </xs:documentation>
     </xs:annotation>
     <xs:complexType mixed="true">
@@ -1230,7 +1235,10 @@
   </xs:element>
   <xs:complexType name="caparesponse--answergroup">
     <xs:annotation>
-      <xs:documentation>Collection of Answers</xs:documentation>
+      <xs:documentation>
+        Collection of Answers.
+        This element can be used instead of the answer attribute on the response element when several answers are correct, or when the correct answer has several components.
+      </xs:documentation>
     </xs:annotation>
     <xs:choice maxOccurs="unbounded">
       <xs:element name="answer" type="caparesponse--answer"/>
@@ -1251,12 +1259,24 @@
   <xs:complexType name="caparesponse--answer">
     <xs:annotation>
       <xs:documentation>
-        Correct list of values or vectors.
+        A correct list of values or vectors.
       </xs:documentation>
     </xs:annotation>
     <xs:choice maxOccurs="unbounded" minOccurs="0">
-      <xs:element name="vector" type="caparesponse--vector"/>
-      <xs:element name="value" type="caparesponse--value"/>
+      <xs:element name="vector" type="caparesponse--vector">
+        <xs:annotation>
+          <xs:documentation>
+            A vector, part of a correct answer.
+          </xs:documentation>
+        </xs:annotation>
+      </xs:element>
+      <xs:element name="value" type="caparesponse--value">
+        <xs:annotation>
+          <xs:documentation>
+            A value, part of a correct answer.
+          </xs:documentation>
+        </xs:annotation>
+      </xs:element>
     </xs:choice>
     <xs:attribute name="name" type="xs:string"/>
     <xs:attribute default="ordered" name="type">
@@ -1291,7 +1311,12 @@
   </xs:annotation>
   <xs:element name="formularesponse">
     <xs:annotation>
-      <xs:documentation>Query for a formula.</xs:documentation>
+      <xs:documentation>
+        Formula Response asks the student to type in a formula as an answer.
+        
+        If the answer is 2x² + 4, the student is allowed to type “2*x*x+4”, “x*x + x*x + 4”, “2*xˆ2 + 14 - 10”, or any other equivalent expression.
+        Formula Response problems have many of the same characteristics of Numerical Response problems, including the ability to run scripts, dynamically generate answers, etc.
+      </xs:documentation>
     </xs:annotation>
     <xs:complexType mixed="true">
       <xs:choice maxOccurs="unbounded" minOccurs="0">
@@ -1304,7 +1329,13 @@
         <xs:group ref="text-only"/>
       </xs:choice>
       <xs:attributeGroup ref="response-identification"/>
-      <xs:attribute name="answer" type="xs:string"/>
+      <xs:attribute name="answer" type="xs:string">
+        <xs:annotation>
+          <xs:documentation>
+            The correct answer. It can use variables calculated/defined in the problem’s Perl script block, allowing the answer to be determined dynamically.
+          </xs:documentation>
+        </xs:annotation>
+      </xs:attribute>
       <xs:attribute name="samples" type="xs:string">
         <xs:annotation>
           <xs:documentation>
@@ -1337,7 +1368,8 @@
   <xs:element name="mathresponse">
     <xs:annotation>
       <xs:documentation>
-        Query for text that is evaluated with a script written in a computer algebra system language by the problem author.
+        Query for text that is evaluated with a script written in a Computer Algebra System (CAS) language.
+        The CAS script must be included in the response with an &lt;answer&gt; element.
         
         MathResponse is extremely powerful, as it tests answers for conditions rather than agreement with a particular correct answer. An unfortunate byproduct, however, is that it cannot be analyzed by several of the LON-CAPA statistics tools.
       </xs:documentation>
@@ -1348,7 +1380,8 @@
         <xs:element name="answer" type="mathresponse--answer">
           <xs:annotation>
             <xs:documentation>
-              Maxima or R script using the arrays RESPONSE and LONCAPALIST.
+              Maxima or R script using the arrays RESPONSE (the student response) and LONCAPALIST (from the args attribute).
+              Returns a boolean in the last statement that will be true if the answer is correct.
             </xs:documentation>
           </xs:annotation>
         </xs:element>
@@ -1364,7 +1397,12 @@
       <xs:attribute name="answerdisplay" type="xs:string">
         <xs:annotation>
           <xs:documentation>
-            String to display for answer
+            This attribute contains what is displayed when the problem is in "Show Answer" mode.
+            You will want to use it so that the students can see the correct answer after
+            the "Show Answer Date" configured when the problem is assigned in the course space.
+            
+            This is usually the name of a Perl string variable (starting with '$')
+            created in a Perl script before the response.
           </xs:documentation>
         </xs:annotation>
       </xs:attribute>
@@ -1388,7 +1426,8 @@
       <xs:attribute name="args" type="xs:string">
         <xs:annotation>
           <xs:documentation>
-            Argument Array
+            Perl array that will be passed to the CAS script as the LONCAPALIST variable.
+            This is usually the name of a Perl array variable (starting with '@') created in a Perl script before the response.
           </xs:documentation>
         </xs:annotation>
       </xs:attribute>
@@ -1396,9 +1435,6 @@
     </xs:complexType>
   </xs:element>
   <xs:complexType mixed="true" name="mathresponse--answer">
-    <xs:annotation>
-      <xs:documentation>Answer algorithm</xs:documentation>
-    </xs:annotation>
     <xs:attribute name="type" type="xs:string"/>
     <xs:attribute fixed="preserve" ref="xml:space"/>
   </xs:complexType>