Merge branch 'iss1703' into dev

Author: sangwinc

doc/en/AbInitio/Authoring_quick_start_1.md

@@ -22,7 +22,7 @@ There are lots of fields, but only a few are compulsory:
 
 1. The "question name",
 2. The "question text", which is shown to the student,
-3. The teacher's "model answer" `ta` using a variable in the "question variables",
+3. The teacher's "model answer" `ta1` using a variable in the "question variables",
 4. A test of "correctness" (defaults to Algebraic equivalence).
 
 By default a new question automatically has one [input](../Authoring/Inputs/index.md), and one algorithm to test correctness of the answer.
@@ -39,10 +39,10 @@ You must give the question a name, for example `question1`.
 
 There should be text in question variables by default.
 
-    ta:?;
+    ta1:?;
 We should replace `?` with the model answer to the question. In this case, this wil be the derivative of \((x-1)^3\), which is \(3(x-1)^2\). So we should replace `?` with `3*(x-1)^2`.
 
-    ta:3*(x-1)^2;
+    ta1:3*(x-1)^2;
 
 
 ### Question text ###
@@ -110,7 +110,7 @@ Each branch can then
 We can leave the default settings for a minimal question, which is the following:
 
 1. Specify the variable `ans1` in the `SAns` setting.
-2. Specify the correct answer in the `TAns` setting: `ta`.
+2. Specify the correct answer in the `TAns` setting: `ta1`.
 3. `AlgEquiv` in the _Answer test_ drop-down menu.
 
 ## Saving the question
@@ -123,7 +123,7 @@ To recap, we have
 
 1. The "question name",
 2. The "question text",
-3. The teacher's "model answer", (`ta` in the question variables).
+3. The teacher's "model answer", (`ta1` in the question variables).
 4. A test of "correctness" (set to Algebraic equivalence).
 
 Next we should try out our question by pressing the `Preview` link at the bottom of the page.

doc/en/AbInitio/Authoring_quick_start_2.md

@@ -25,8 +25,8 @@ We make more use of the question text field. For instance, we can start to use t
 Add the following to the question variables
 
 ```
-exp: 3*(x-1)^(-4);
-ta: int(exp,x)+c;
+ex1: 3*(x-1)^(-4);
+ta1: int(ex1,x)+c;
 ```
 
 The coding in question variables is based on Maxima, which has an unusual syntax for assignment.  In particular, the colon `:` is used to assign a value to a variable.  So to assign the value of `5` to `a1`, we use the syntax `a1:5`. In general, it is good practice to give variables multi-character names, as single-character names are meant for student input. This is because multi-character variables the author defined cannot by default be input by students. Additionally, adding semicolons to the end of each line is optional, but good practice.
@@ -35,21 +35,21 @@ Notice we are using the CAS to determine the model answer by calling the `int()`
 
 Now it will be a lot faster to fill out the rest of the question. Add the following to the question text:
 
-	<p>Find \(\int{@exp@} \mathrm{d}x\)</p>
+	<p>Find \(\int{@ex1@} \mathrm{d}x\)</p>
 	<p>[[input:ans1]] [[validation:ans1]]</p>
 
-Notice that we have defined a local variable `exp`, and used the value of this in the Question text. There is a difference between mathematics enclosed between `\(..\)` symbols and `{@..@}` symbols. All the text-based fields in the question, including feedback, are [CAS text](../Authoring/CASText.md).  This is HTML into which mathematics can be inserted.  LaTeX is placed between `\(..\)`s, and CAS expressions (including your variables) between matching `{@..@}` symbols.  The CAS expressions are evaluated in the context of the question variables and displayed as LaTeX.
+Notice that we have defined a local variable `ex1`, and used the value of this in the Question text. There is a difference between mathematics enclosed between `\(..\)` symbols and `{@..@}` symbols. All the text-based fields in the question, including feedback, are [CAS text](../Authoring/CASText.md).  This is HTML into which mathematics can be inserted.  LaTeX is placed between `\(..\)`s, and CAS expressions (including your variables) between matching `{@..@}` symbols.  The CAS expressions are evaluated in the context of the question variables and displayed as LaTeX.
 
-Since we have used `{@exp@}` here, the user will not see a \(exp\) on the screen when the question is instantiated, but the _displayed value_ of `exp`: \(\frac{3}{(x-1)^{-4}}\)
+Since we have used `{@ex1@}` here, the user will not see a \(ex1\) on the screen when the question is instantiated, but the _displayed value_ of `ex1`: \(\frac{3}{(x-1)^{-4}}\)
 
-In the input `ans1`, confirm the default `model answer` is the variable `ta`.
+In the input `ans1`, confirm the default `model answer` is the variable `ta1`.
 
-In the potential response tree, confirm the default `Answer test` is  `AlgEquiv`, `SAns` is `ans1` and `TAns` is `ta`.
+In the potential response tree, confirm the default `Answer test` is  `AlgEquiv`, `SAns` is `ans1` and `TAns` is `ta1`.
 
 It is good practice to use question variables often, as they save time and let you change properties of the question easily in the future.
 
 # Next step #
 
 You should now be able to use question variables in STACK.
 
-##### The next part of the authoring quick start guide looks at [improving feedback](Authoring_quick_start_3.md).
+##### The next part of the authoring quick start guide looks at [improving feedback](Authoring_quick_start_3.md).

doc/en/AbInitio/Authoring_quick_start_3.md

@@ -9,7 +9,7 @@ This part of the Authoring Quick Start Guide deals with improving feedback. The
 <iframe width="560" height="315" src="https://www.youtube.com/embed/l6QAMmUA5Pk" frameborder="0" allowfullscreen></iframe>
 ## Introduction
 
-In the last part we started working with question variables. Specifically, we defined the variable  `exp` for the expression to be integrated, and `ta` for the teacher's answer. Then we asked the student to find \(\int 3(x-1)^{-4}dx\).
+In the last part we started working with question variables. Specifically, we defined the variable  `ex1` for the expression to be integrated, and `ta1` for the teacher's answer. Then we asked the student to find \(\int 3(x-1)^{-4}dx\).
 
 Try previewing this question and typing in  `-1*(x-1)^(-3)+c`. The system should accept this as correct.  Next type in `-1*(x-1)^(-3)+C`.  This will be compared to the teacher's answer `-1*(x-1)^(-3)+c` by algebraic equivalence (recall we specified `AlgEquiv` in the potential response tree), and will not be accepted as equivalent.  The reason is that `c` and `C` are different.  A reasonable teacher will probably not care which letter is used for the constant of integration. Let us fix this problem.
 

doc/en/AbInitio/Authoring_quick_start_4.md

@@ -14,23 +14,23 @@ In the last part, we worked with a problem about integrating \(3(x-1)^{-4}\) wit
 Let's take a look again at the question variables we declared:
 
 ```
-exp: 3*(x-1)^(-4);
-ta: int(exp,x)+c;
+ex1: 3*(x-1)^(-4);
+ta1: int(ex1,x)+c;
 ```
 
-We defined two local variables `exp` and `ta`, and used these values in other places such as the question text, input and potential response tree. 
+We defined two local variables `ex1` and `ta1`, and used these values in other places such as the question text, input and potential response tree. 
 
 We are now in a position to generate a random question. To do this, modify the [question variables](../Authoring/Variables.md#Question_variables) to be
 
 ```
 a1 : 1+rand(6);
 a2 : 1+rand(6);
 nn : 1+rand(4);
-exp : a1*(x-a2)^(-nn);
-ta: int(exp, x)+c;
+ex1 : a1*(x-a2)^(-nn);
+ta1: int(ex1, x)+c;
 ```
 
-In this new question we are asking the student to find the anti-derivative of a question with a definite form \( a_1(x-a_2)^{-nn} \). `a1`, `a2` and `nn` are all variables which are assigned random positive integers.  These are then used to define the variable `exp`, used in the question itself. We also have the CAS integrate the expression `exp` and store the result in the variable `ta`. It is good practice to use variables names with more than one character as single-character variables, like `x`, are meant for student input.
+In this new question we are asking the student to find the anti-derivative of a question with a definite form \( a_1(x-a_2)^{-nn} \). `a1`, `a2` and `nn` are all variables which are assigned random positive integers.  These are then used to define the variable `ex1`, used in the question itself. We also have the CAS integrate the expression `ex1` and store the result in the variable `ta1`. It is good practice to use variables names with more than one character as single-character variables, like `x`, are meant for student input.
 
 Remember that when generating random questions in STACK we talk about _random numbers_ when we really mean _pseudo-random numbers_. To keep track of which random numbers are generated for each user, there is a special `rand` command in STACK, which you should use instead of [Maxima](../CAS/Maxima_background.md)'s random command. The `rand` command is a general "random thing" generator, see the page on [random generation](../CAS/Random.md) for full details. `rand` can be used to generate random numbers and also to make selections from a list. `rand(n)` will select a random integer from 0 up to, **and not including**, `n`. So  `rand(3)` will select a random number from the list  `[0,1,2]` .
 
@@ -40,7 +40,7 @@ Now that as our question contains random numbers, we need to record the actual q
 Fill the question note in as
 
 ```
-\[ \int {@exp@} \mathrm{d}x = {@ta@}.\]
+\[ \int {@ex1@} \mathrm{d}x = {@ta1@}.\]
 ```
 
 Two question variants are considered to be the same if and only if the question note is the same. It is the teacher's responsibility to create sensible notes.

doc/en/AbInitio/Authoring_quick_start_5.md

@@ -13,8 +13,8 @@ In the last couple of parts, we have been working with a simple integration ques
 a1 : 1+rand(6);
 a2 : 1+rand(6);
 nn : 2+rand(4);
-exp : a1*(x-a2)^(-nn);
-ta: int(exp, x)+c;
+ex1 : a1*(x-a2)^(-nn);
+ta1: int(ex1, x)+c;
 ```
 
 Testing questions is time consuming and tedious, but important to ensure questions work.  To help with this process, STACK enables teachers to define "question tests".  The principle is the same as "unit testing" in software engineering.
@@ -30,22 +30,22 @@ The penalty is a number deducted from the total mark for each incorrect attempt
 Fill in the following information for your first test case:
 
 ```
-ans1 = ta
+ans1 = ta1
 score = 1
 penalty = 0
 answernote = prt1-2-T
 ```
 
 I.e., if the student puts in the model answer they should pass the first node (checks if they have integrated correctly) and pass the second node (tests that their answer is factored) and end up with a score of 1 and no penalty. 
 
-Note that the input is evaluated before the test is conducted. Students are not allowed to enter the variable  `ta` because it is a teacher-defined variable, however the evaluated form, fx.  `-1*(x-1)^(-3)+c`, is an allowed input. For each test case, you can see the un-evaluated input under `Test input`, and the actual input tested under `Value entered`. 
+Note that the input is evaluated before the test is conducted. Students are not allowed to enter the variable  `ta1` because it is a teacher-defined variable, however the evaluated form, fx.  `-1*(x-1)^(-3)+c`, is an allowed input. For each test case, you can see the un-evaluated input under `Test input`, and the actual input tested under `Value entered`. 
 
 You can run the test on all deployed versions by clicking on  `Run all tests on all deployed variants` .
 
 You can add as many tests as you think is needed, and it is usually a sensible idea to add one for each case you anticipate.  Add in another test case for
 
 ```
-ans1 = int(exp,x)
+ans1 = int(ex1,x)
 score = 0
 penalty = 0.1
 answernote = prt1-1-F

doc/en/Authoring/Question_blocks/Static_blocks.md

@@ -92,6 +92,12 @@ The template block has two parameters, the first being a name which should be a
 
 Note in the background templates are just functions with CASText values. You can do the same with inline CASText and more importantly building your own functions allows you to use arguments for them and thus makes repetition with varying parameters simpler. For templates no arguments exist, for them the values come from the context where they get placed in, and must therefore be controlled though other means.
 
+Note that if you wish to use a template in both the question text and in the PRT feedback, you will need to define it in the question variables (in particular, if you define the template in the question text, it will not work in the PRT feedback since the PRT feedback is evaluated in a different scope from the question text). For instance:
+
+    define_my_template: castext("[[template name="foobar"]]Whatever is {@whatever@}[[/template]]");
+
+You can then use `[[template name="foobar"/]]` throughout the question.
+
 ## Entity escape block ##
 
 Sometimes one needs to author content that uses characters that are sensitive in HTML syntax. If one wraps that content in this block those characters will be automatically converted to HTML-entities during output. Can be very useful when including sample blocks of code, that includes certain operators. `[[entityescape]] code with some less than chars [[/entityescape]]`.

doc/en/Developer/Development_track.md

@@ -11,28 +11,23 @@ Issues with [github milestone 4.13.0](https://github.com/maths/moodle-qtype_stac
 
 1. Remove all "cte" code from Maxima - mostly install.
 2. Support for Maxima 5.47.0, 5.48.0, and 5.49.0.  This includes a fix for issue #1281 from 5.48.0.
+3. Question tests can now test the whole route through a PRT, rather than just the final node.  This is a significant improvement on the ability to test questions.  This is back-compatible with older questions.
 
 --------------------------------------
-## Testing a node, not a whole tree
 
-This section is a detailed design proposal to improve question testing to test a node, not a whole tree, and address issue #1703.
-
-### Change of `expectedanswernote`
-
-Make DB changes to considerably lengthen `expectedanswernote` from 255 chars:  https://github.com/maths/moodle-qtype_stack/blob/master/db/install.xml#L178
+## Better testing
 
 ### Add in a new keyvals field "test variables".
 
 Add in a new keyvals field "test variables". The test execution would then take three CAS sessions.
 
-   1.  Loading up the seed, question variables, test variables and all input definitions, generating input "strings".
+   1. Loading up the seed, question variables, test variables and all input definitions, generating input "strings".
    2. Those "strings" would then go through PHP side input validation and CAS side validation in the second CAS session.
    3. Finally, the valid strings would be fed to the PRT functions in the last session, and logic to check if the PRT output matches would be included in that session, so that we do not need to output the full PRT function output for potentially a large number of tests, instead just booleans.
 
-### Other ideas (later)
+Other ideas
 
 1. It would be a fun (student project?!) to graphically illustrate the expected and actual route through the tree by expanding the current PRT graph library, or writing something else. (I get ahead of myself of course....)
-
 2. Introduce new keyword `any` in score/penalty effectiveley ignoring that field for the purposes of this test case.
 
 Currently, the DB fields for score and penalty are numbers, specifically
@@ -42,7 +37,6 @@ Currently, the DB fields for score and penalty are numbers, specifically
 
 So this requires a DB change as well.
 
-
 --------------------------------------
 
 ## Future Adapt block development ideas

stack/maxima/contrib/vectorgeometry.mac

@@ -115,9 +115,12 @@ vector_parametric_parts(vec, [exclude_params]):=block([simp:true, vars, nonlinva
  * @param[list] parts A list with three elements (see vector_parametric_parts) [mx1 matrix of constants, a list of mx1 matrices of constants, a list of variable names]
  * @return[string] TeX output of a vector parametric equation in a "standard" form.
  */
-vector_parametric_display(parts):= block([simp:false,cons_vec,dir_vecs,vars],
+vector_parametric_display(parts):= block([simp:false,cons_vec,dir_vecs,vars,cons_p,dir_p],
   [cons_vec,dir_vecs,vars]: parts,
-  return(sconcat(tex1(cons_vec),"+",tex1(apply("+", zip_with("*", vars, dir_vecs)))))
+  cons_p: if ev(zeromatrixp(cons_vec),simp) then "" else tex1(cons_vec),
+  if emptyp(dir_vecs) then dir_p: [] else dir_p: zip_with("*", vars, dir_vecs),
+  if is(length(dir_p)=0) then dir_p: "" else if is(length(dir_p)=1) then dir_p: tex1(first(dir_p)) else dir_p: tex1(apply("+",dir_p)),
+  return(sconcat(cons_p,if is(cons_p="") or is(dir_p="") then "" else "+",dir_p))
 );
 
 /**

stack/maxima/contrib/vectorgeometry_test.mac

@@ -59,6 +59,10 @@ s_test_case(vector_parametric_parts(matrix([1],[2],[3]) + t*matrix([1],[1],[1])
 make_multsgn("dot");
 s_test_case(vector_parametric_display([matrix([1],[2],[3]),[matrix([1],[0],[1]),matrix([1],[1],[1])],[s,t]]),"\\left[\\begin{array}{c} 1 \\\\ 2 \\\\ 3 \\end{array}\\right]+s\\cdot \\left[\\begin{array}{c} 1 \\\\ 0 \\\\ 1 \\end{array}\\right]+t\\cdot \\left[\\begin{array}{c} 1 \\\\ 1 \\\\ 1 \\end{array}\\right]");
 s_test_case(vector_parametric_display(vector_parametric_parts(matrix([1+t+s],[2+t],[3+t+s]))),"\\left[\\begin{array}{c} 1 \\\\ 2 \\\\ 3 \\end{array}\\right]+s\\cdot \\left[\\begin{array}{c} 1 \\\\ 0 \\\\ 1 \\end{array}\\right]+t\\cdot \\left[\\begin{array}{c} 1 \\\\ 1 \\\\ 1 \\end{array}\\right]");
+s_test_case(vector_parametric_display(vector_parametric_parts(c(1,2,3))),"\\left[\\begin{array}{c} 1 \\\\ 2 \\\\ 3 \\end{array}\\right]");
+s_test_case(vector_parametric_display(vector_parametric_parts(c(1,2,3) + t*c(2,3,4))),"\\left[\\begin{array}{c} 1 \\\\ 2 \\\\ 3 \\end{array}\\right]+t\\cdot \\left[\\begin{array}{c} 2 \\\\ 3 \\\\ 4 \\end{array}\\right]");
+s_test_case(vector_parametric_display(vector_parametric_parts(t*c(2,3,4))),"t\\cdot \\left[\\begin{array}{c} 2 \\\\ 3 \\\\ 4 \\end{array}\\right]");
+s_test_case(vector_parametric_display(vector_parametric_parts(t*c(2,3,4) + s*c(3,4,5))),"s\\cdot \\left[\\begin{array}{c} 3 \\\\ 4 \\\\ 5 \\end{array}\\right]+t\\cdot \\left[\\begin{array}{c} 2 \\\\ 3 \\\\ 4 \\end{array}\\right]");
 
 s_test_case(point_in_affine_spacep(matrix([1],[1]),[matrix([0],[1]),[matrix([1],[-1])]]),false);
 s_test_case(point_in_affine_spacep(matrix([1],[1]),[matrix([0],[1]),[matrix([1],[-1])],[t]]),false);