Skip to content
Snippets Groups Projects
Commit d4301f3b authored by csangwin's avatar csangwin
Browse files

Update the docs (mostly spell checking)

parent 2d6c1ba6
No related branches found
No related tags found
No related merge requests found
Showing
with 220 additions and 244 deletions
......@@ -6,7 +6,7 @@ STACK inputs and the state of the graph consists of three important things:
1. We need to turn the state we wish to store into a string when it needs to be stored.
2. We need to be able to restore the state from a string when need be, typically on page
load or during two-way binding style usage.
3. We need to know when those things need to happen, i.e. what interractions with the graph
3. We need to know when those things need to happen, i.e. what interactions with the graph
trigger the first point and when to trigger the second.
As this is almost always the same for all bindings the `stack_jxg` library provides a general
......@@ -38,7 +38,7 @@ There are things that may not be obvious, here are some that are worth noting:
that is enough to restore it, but the serialisation could still contain various angles
or other helpful details in addition to those points so that you do not need to calculate
them in Maxima.
2. The countter point to that is that you should never trust anything coming from
2. The counter point to that is that you should never trust anything coming from
the browser and nothing grading related should be calculated in the browser. However,
it is pretty rare to see a student modifying the serialised state stored in the input
so that it would contain wrong grading details, so do what feels natural. What is likely
......@@ -324,7 +324,7 @@ At 1. the serialiser is rather simple, if yours is not consider whether the way
state is clear enough. Typically, well constructed state is easy to serialise.
At 2. the key thing to note is that when we create new elements that need to be bound we need
to register them, unregistering is not possible and one should probably not care about that, as
to register them, un-registering is not possible and one should probably not care about that, as
extra registered items, while taking room and time during evaluation of logic are not that
common and will be dropped during page refresh. Typically, users do not do so many actions that
the lag would be noticeable.
......
......@@ -23,7 +23,7 @@ Notes
In order to understand how the tests work it is essential to understand how we represent unary minus and division internally.
Without simplification, Maxima has a unary minus function. Litterally `minus(x)`. This is transformed into `UNARY_MINUS nounmul ex` The use of multiplication here allows `-` to commute with other multiplication, so we can spot things like \(-x \times -y = --xy\) using associativity and commutativity.
Without simplification, Maxima has a unary minus function: literally `minus(x)`. This is transformed into `UNARY_MINUS nounmul ex` The use of multiplication here allows `-` to commute with other multiplication, so we can spot things like \(-x \times -y = --xy\) using associativity and commutativity.
Similarly, we replace division \(a/b\) with `a nounmul UNARY_RECIP(b)`. This means that `UNARY_RECIP(b)` is not automatically the same as `1 nounmul UNARY_RECIP(b)`, without an additional rule.
......@@ -31,7 +31,7 @@ Similarly, we replace division \(a/b\) with `a nounmul UNARY_RECIP(b)`. This me
This is an advanced test.
This test allows question authors to create equivalence classes based on equality up to associativity and commutativity with the addition of optional rules. For example, the teacher can include the identity operations of addition and multiplication: \(0+ x\rightarrow x\) and \(1\times x\rightarrow x\). This makes it much easier to establish things like \(0-1\times i\) is equivalent to \(-i\). However, more general integer arithmatic is still not automatically included so \(2\times 3 \neq 6\).
This test allows question authors to create equivalence classes based on equality up to associativity and commutativity with the addition of optional rules. For example, the teacher can include the identity operations of addition and multiplication: \(0+ x\rightarrow x\) and \(1\times x\rightarrow x\). This makes it much easier to establish things like \(0-1\times i\) is equivalent to \(-i\). However, more general integer arithmetic is still not automatically included so \(2\times 3 \neq 6\).
This test always assumes associativity and commutativity of addition and multiplication. Essentially this test extends the `EqualComAss` test by adding in additional rules. Without assumptions of commutativity and associativity we would need all sorts of additional rules, such as \(x+0 \rightarrow x\), since without commutativity this would not be captured by the rule `zeroAdd`, i.e. \(0+x \rightarrow x\). Furthermore, the way `EqualComAss` deals with unary minus and division make associativity and commutativity difficult to add in their pure form.
......@@ -75,16 +75,16 @@ The teacher must supply an option consisting of a list of the following rule nam
The rule `negOrd` deserves comment. Ultimately we only compare parse trees exactly, and so we need to order terms in sums and products (commutativity).
However \(y-x\) is never ordered as \(-x+y\). Furthermore, \(-(x-y) \neq -x+y\). We need to factor out the unary minus and ensure that the coefficient of the leading term is not negative.
Factoring out is better than distributing here, since in a produce such as \(-(x-y)(x-z)\) it is not clear which term in the product the inital minus sign will end up in.
Factoring out is better than distributing here, since in a produce such as \(-(x-y)(x-z)\) it is not clear which term in the product the initial minus sign will end up in.
Since `negOrd` is a factor command, it is incompatible with `negDist`.
For convenience sets of rules can be specificed. E.g. you can use the name `ID_TRANS` in place of the list `[zeroAdd,zeroMul,oneMul,oneDiv,onePow,idPow,zeroPow,zPow]` to include all of the basic identity operators.
For convenience sets of rules can be specified. E.g. you can use the name `ID_TRANS` in place of the list `[zeroAdd,zeroMul,oneMul,oneDiv,onePow,idPow,zeroPow,zPow]` to include all of the basic identity operators.
If you want to remove tests from a list you can use code such as `delete(zeroAdd, ID_TRANS)`.
The test takes the student's answer and teacher's answer and repeatedly applies the rules in turn until the expressions remain the same. The rules are designed to always shorten the expression, so the process is guranteed to terminate. Once the expression is written in final form, the test compares the two expression trees.
The test takes the student's answer and teacher's answer and repeatedly applies the rules in turn until the expressions remain the same. The rules are designed to always shorten the expression, so the process is guaranteed to terminate. Once the expression is written in final form, the test compares the two expression trees.
Note that we do not gurantee the simplification is mathematically correct! E.g. if you are unlucky enough to try the rule `zeroPow` on the expression `0^(1-1)` then since `1-1` is not equal to zero (taken literally) then the rule applies and you have failed to spot a potential `0^0` error.
Note that we do not guarantee the simplification is mathematically correct! E.g. if you are unlucky enough to try the rule `zeroPow` on the expression `0^(1-1)` then since `1-1` is not equal to zero (taken literally) then the rule applies and you have failed to spot a potential `0^0` error.
If you add the rule `testdebug` then you will see both expressions in the answer note. This is useful for debugging, but would clutter up things in a production setting.
......@@ -101,9 +101,9 @@ Note, this test always assumes commutativity so you can't (currently) enforce th
## Developer notes ##
This functionality was introduced in April 2021. It is essential that the rules, and any combination of the rules, can only proceed in a single direction and that no infinite loops are created. So, `intAdd` is fine because adding together two integers will make an expression _simpler_ which in this case is shorter. For this reason we do not have expanding out (i.e. distribution) rules in the above set, and no rules of indices (which readily lead to mathemtical errors). Use Maxima's simplifier if you want to include such rules.
This functionality was introduced in April 2021. It is essential that the rules, and any combination of the rules, can only proceed in a single direction and that no infinite loops are created. So, `intAdd` is fine because adding together two integers will make an expression _simpler_ which in this case is shorter. For this reason we do not have expanding out (i.e. distribution) rules in the above set, and no rules of indices (which readily lead to mathematical errors). Use Maxima's simplifier if you want to include such rules.
The rules names are Maxima functions, but they assume `simp:false` and that the expression has noun forms e.g. `nounadd` instead of `+`. You can use `equals_commute_prepare(ex)` to change an expression into this noun form. The goal of this code is to create reliable equivalence classes of expressions, not perform algebraic manipulation as we traditionally know it. In particular the way unary minus is transformed into multiplication with a special tag `UNARY_MINUS` is likely to cause confusion to students if an expression is manipulated using these rules and then shown to a student. The transoformation is designed to go in one direction only, and we do not support displaying the resulting manipulated expressions in traditional form.
The rules names are Maxima functions, but they assume `simp:false` and that the expression has noun forms e.g. `nounadd` instead of `+`. You can use `equals_commute_prepare(ex)` to change an expression into this noun form. The goal of this code is to create reliable equivalence classes of expressions, not perform algebraic manipulation as we traditionally know it. In particular the way unary minus is transformed into multiplication with a special tag `UNARY_MINUS` is likely to cause confusion to students if an expression is manipulated using these rules and then shown to a student. The transformation is designed to go in one direction only, and we do not support displaying the resulting manipulated expressions in traditional form.
__As of May 2023, these rules are not intended as an end-user simplifier and we do not currently support user-defined rules (sorry!).__
......
......@@ -22,7 +22,7 @@ This test uses Maxima's `regex_match` function.
* The first argument should be the string, and the second argument should be the pattern to match.
* It yields true if the pattern is matched anywhere within the student answer and false otherwise. Testing for full equality of the answer string can be achieved via regex anchoring by use of `^` or `$`.
* Don't forget to escape within the pattern strings as needed. Note that there is a function `string_to_regex()` that will handle escaping of characters that would otherwise have meaning in the pattern. Also remember that you need to escape the backslashes like normal in Maxima-strings. That is to say, if you want to use `\s` in a pattern you need to double up the backslashes. For example `"(Alice|Bob)\\s+went\\s+to\\s+the\\s+(bank|market)"`.
* One can read more about the patterns posible from [here](http://ds26gte.github.io/pregexp/index.html). Case-insensitivity may be something worth noting there.
* One can read more about the patterns possible from [here](http://ds26gte.github.io/pregexp/index.html). Case-insensitivity may be something worth noting there.
For example, write a STACK question with the following question variables.
......
......@@ -76,7 +76,7 @@ Documentation is grouped as follows.
* [EquivFirst](../../CAS/Equivalence_reasoning.md)
* [PropLogic](../../Topics/Propositional_Logic.md)
## Pre-pocessing students' answers ##
## Pre-processing students' answers ##
You can apply functions before applying the tests using the feedback variables. For example, to ignore case sensitivity you can apply the [Maxima commands defined by STACK](../../CAS/Maxima.md#Maxima_commands_defined_by_STACK) `exdowncase(ex)` to the arguments, before you apply one of the other answer tests. However, some tests really require the raw student's input. E.g. the numerical decimal place test really requires the name of an input as the `SAns` field. If you manipulate an input, you may end up dropping trailing zeros and ruining the number of decimal places in the expression. STACK will warn you if you need to use the name of an input.
......
......@@ -2,4 +2,4 @@
STACK provides a structured [author quick start guide](../AbInitio/Authoring_quick_start_1.md) for new users.
This guide has been used by many people, but we accept that authoring questions is a complex process. Developing expertise in authoring STACK questions will require some commitement.
This guide has been used by many people, but we accept that authoring questions is a complex process. Developing expertise in authoring STACK questions will require some commitment.
......@@ -63,15 +63,13 @@ To place another potential response tree in the question just choose a sensible
General feedback (called "worked solution" in previous versions) is shown to the student after they have attempted the question. Unlike feedback, which depends on the response the student gave, the same general feedback text is shown to all students.
The general feedback may depend on any question variables, but may _not_ depend on any of the inputs.
While this design decision is restrictive, it is a deliberate separation of feedback
which should be done via potential response trees, from a model solution to this
problem which can be written before a question is deployed.
While this design decision is restrictive, it is a deliberate separation of feedback which should be done via potential response trees, from a model solution to this problem which can be written before a question is deployed.
## CASText and currency {#currency}
It is common to want to use the dollar sign for currency. However, this conflicts with the use of the dollar sign for delimiters for mathematics. For this reason we discourage the use of dollars to delimit mathematics in STACK.
* If you are using dollars for currency then you must protect them with a backslash, i.e. `\$`, otherwise the CASText validation will fail.
If you are using dollars for currency then you must protect them with a backslash, i.e. `\$`, otherwise the CASText validation will fail.
## Facts ##
......@@ -87,7 +85,7 @@ HTML and LaTeX are needed for authoring STACK questions, and some basic referenc
## CASText generating functions ##
If a CASText area is to include several copies of repeatative content, for instance several versions of some text (or a SVG graphic) containing
If a CASText area is to include several copies of repetitive content, for instance several versions of some text (or a SVG graphic) containing
different parameters, it is possible to define a CASText generating function within the Question variables using the STACK function `castext`.
For example, within the [Question variables](Variables.md) section, define
......
......@@ -115,9 +115,7 @@ If you really want the term order as well, as in, \(x^{3}+6x^{2}+12x+8\) then yo
At this point, any expressions which are equivalent are considered to be a legitimate step.
Clearly this is not entirely satisfactory.
At this point in the development there is no concept of "a step" and indeed this appears to be very hard to define.
In the future we will develop better tools for checking "step size", and any contributions in this direction are welcome.
Clearly this is not entirely satisfactory. At this point in the development there is no concept of "a step" and indeed this appears to be very hard to define. In the future we will develop better tools for checking "step size", and any contributions in this direction are welcome.
Teachers can check the students answer is long enough or not too long by looking at `length(ta)`.
......
......@@ -2,7 +2,7 @@
How to I trap errors generated from a student's answer?
Errors are generated for a number of reasons. Mostly, they are important and should not be ignored! Normally, students should not be penalised if a question "does not work" because the PRT generated an error. Any runtime error during traversing a PRT will cause an error. This error will stop further exectution of the tree, and students will see a runtime error message. This will be flagged in the response summary as `[RUNTIME_ERROR]`.
Errors are generated for a number of reasons. Mostly, they are important and should not be ignored! Normally, students should not be penalised if a question "does not work" because the PRT generated an error. Any runtime error during traversing a PRT will cause an error. This error will stop further execution of the tree, and students will see a runtime error message. This will be flagged in the response summary as `[RUNTIME_ERROR]`.
A student's answer can generate mathematical errors for a number of reasons, but the most common is evaluating a function outside its mathematical domain. Common elementary examples are
......@@ -18,7 +18,7 @@ If one of the feedback variables throws an error then this will not stop the PRT
sa1:errcatch(tan(ans1));
If `ans1:%pi/2` then `sa1` will be the empty list `[]`. Otherwise, `sa1` will be the list containg the result, and you can use `first(sa1)` in a PRT.
If `ans1:%pi/2` then `sa1` will be the empty list `[]`. Otherwise, `sa1` will be the list containing the result, and you can use `first(sa1)` in a PRT.
To trap a runtime error, or create a guard clause, you do need extra node in your tree (e.g. is `sa1` empty) or an `if` statement in your feedback variables. The default is to show errors, so if you choose to test for and condone errors you need extra clauses.
......@@ -21,7 +21,7 @@ Some functions affecting the underlying system are forbidden to protect
the environment, others are forbidden due to excessive load, and finally some
have been disabled due to the way they return their values. Likewise, some
variables/constants representing the state of the underlying system have
been either marked as forbbiden to access or to modify. Use other names
been either marked as forbidden to access or to modify. Use other names
if this was just a collision of identifiers, otherwise this is just the way
it is.
......@@ -39,13 +39,9 @@ We suggest you do not attempt to redefine function names or constants which are
## Substitutions unclear or otherwise
Should you do substitutions of values in your code and the target of
the substitution is an identifier that is later used as a function-name,
Should you do substitutions of values in your code and the target of the substitution is an identifier that is later used as a function-name,
things may become difficult. Avoid using the same name for functions and variables.
Also if you use complex means to construct the substitutions themselves the system may need to assume that all
possible identifiers in the expression that the substitutions are applied
to are being targetted by unknown values, this can be avoided by avoiding
complex construction of the substs itself.
Also if you use complex means to construct the substitutions themselves the system may need to assume that all possible identifiers in the expression that the substitutions are applied to are being targeted by unknown values, this can be avoided by avoiding complex construction of the substitution itself.
Note, these issues are now much rarer after the security system changed in 4.4. Yo should not even see these errors with the new system.
......@@ -92,12 +88,7 @@ TAns12 : subst([%k2=A,%k1=B],solution);
## Use of the students answer
Since 4.3 you have been forbidden from writing to the variable storing
the students answer, feel free to simply store whatever you wanted to
store in any other valid variable. You are now also forbidden from using
the students input directly as a function-name, if you need to do so
rewrite the logic as a "switch", unfortunately this also applies to MCQ
inputs:
Since 4.3 you have been forbidden from writing to the variable storing the students answer, feel free to simply store whatever you wanted to store in any other valid variable. You are now also forbidden from using the students input directly as a function-name, if you need to do so rewrite the logic as a "switch", unfortunately this also applies to MCQ inputs:
```
/* Not like this. */
......@@ -114,11 +105,7 @@ else if(ans1=sin) then
## `ev` in 4.4
The new security model of STACK 4.4 modifies the order of execution in such
a way that `ev` does not quite match the behaviour of `ev` in Maxima. For
most use cases you will not notice this but there are situations where
things won't work as expected. In general, these are the situations currently
known:
The new security model of STACK 4.4 modifies the order of execution in such a way that `ev` does not quite match the behaviour of `ev` in Maxima. For most use cases you will not notice this but there are situations where things won't work as expected. In general, these are the situations currently known:
1. Placing `expand` inside of `ev` and doing a substitution in the same `ev`:
```
......
......@@ -35,7 +35,7 @@ If your CASText document contains scripts like JSXGraph content definitions you
__All external files/links are bad!__ If you have images or other documents related to the question they should be included in the question. Avoid embedded frames, applets and other interactive content. To test inclusion you should be able to export the question and import it to a freshly installed raw system on a computer not connected to the internet and those questions should work. *There is nothing wrong with internal files of any type, as long as they come with the question.* Use of the [include](Inclusions.md) feature from 4.4 is also a bad thing, but you can make it less bad if the included file is present on a public server and if it is versioned so that one can link to a version that never changes.
STACK does provide the option for [inclusions](Inclusions.md) within questions. If you regularly use `stack_inlude` in your questions please consider contributing your libraries to the STACK core code. Contributing tested libraries is the best way to ensure longer term maintainance!
STACK does provide the option for [inclusions](Inclusions.md) within questions. If you regularly use `stack_inlude` in your questions please consider contributing your libraries to the STACK core code. Contributing tested libraries is the best way to ensure longer term maintenance!
## Writing CAS code
......@@ -66,7 +66,7 @@ Please note that the system administrator has access to a "bulk test" script whi
There have been some changes, which have created broken questions between versions.
* List instantiation in Maxima is now required by Maxima and writing to an uninstantiated list gives errors like 'ARRSTORE: use_fast_arrays=false; allocate a new property hash table'. Basically, this means that you cannot say `TAns[1]:x;` without first saying `TAns:[];`. So do not assume that Maxima knows you want to create a list by simply assigning to an index on an undefined variable.
* List instantiation in Maxima is now required by Maxima and writing to an un-instantiated list gives errors like 'ARRSTORE: use_fast_arrays=false; allocate a new property hash table'. Basically, this means that you cannot say `TAns[1]:x;` without first saying `TAns:[];`. So do not assume that Maxima knows you want to create a list by simply assigning to an index on an undefined variable.
* Maxima has its own `addrow` command, that differs from STACKs version. Please check any questions using `addrow`. Eventually, a conversion will be made that will switch the arguments of function calls in old questions using the old STACK version of that function but the change process will be long.
......
# Inclusions
This is an expert level topic, please avoid this feature unless you feel that you
understand the implications and concecuences of it. Note that using this feature
goes against the self-contained material principle present in [the future proof guidelines](Future_proof.md).
This is an expert level topic, please avoid this feature unless you feel that you understand the implications and consequences of it. Note that using this feature goes against the self-contained material principle present in [the future proof guidelines](Future_proof.md).
That being said, a common request on the wish-list has been to provide some means
of sharing code between questions. The inclusion-feature is the first step towards
such a feature, however, it is not perfect nor do we expect it to be the solution
that will finally be selected. But we provide it now that the backend has the tools
to provide it, for those adventurous enough.
That being said, a common request on the wish-list has been to provide some means of sharing code between questions. The inclusion-feature is the first step towards such a feature, however, it is not perfect nor do we expect it to be the solution that will finally be selected. But we provide it now that the back-end has the tools to provide it, for those adventurous enough.
Technical note: Currently, inclusions within inclusions are not supportted, due to
loop detection and security validation reasons.
Technical note: Currently, inclusions within inclusions are not supported, due to loop detection and security validation reasons.
## Inclusions life-cycle
......@@ -75,7 +68,7 @@ The included material must follow all the rules of normal STACK keyvals.
3. Identifiers in your code will be marked as forbidden-words for the students. So particular care should be taken when choosing identifiers in such shared logic between questions. Do not use names a student might need to type in another, un-related, question!
4. Code is loaded when you save the question, not when a student uses the question. Hence code is cached in the question. Updates to an external library will therefore not affect existing questions. That cache will not invalidate unless you (a) update the STACK plugin (which clears all cached/compiled questions), (b) save the question (which again downloads the code).
Note that we do not do "tree-shaking" at this point to remove unnecessary code. If you include a massive library of functions that you do not use the question will still have to load those functions into the CAS and that may take some time. If you have libraries, used in many questions, please consider contibuting these to the core of STACK.
Note that we do not do "tree-shaking" at this point to remove unnecessary code. If you include a massive library of functions that you do not use the question will still have to load those functions into the CAS and that may take some time. If you have libraries, used in many questions, please consider contributing these to the core of STACK.
To include external CAS code call the `stack_include()`-function with a string argument. The argument must be a raw string, containing the URL of the code. You cannot reference a variable containing such a string. For example,
......
......@@ -119,7 +119,7 @@ This input type can be used for
1. surveys;
2. answers which are not automatically marked, contributing to [semi-automatic marking](../Moodle/Semi-automatic_Marking.md).
The notes input has a special extra option `manualgraded`, and the default option value is `manualgraded:false`. If you specify `manualgraded:true` then the _whole STACK quesion_ will require manual grading!
The notes input has a special extra option `manualgraded`, and the default option value is `manualgraded:false`. If you specify `manualgraded:true` then the _whole STACK question_ will require manual grading!
#### Single Character ####
......@@ -330,7 +330,7 @@ More information on subscripts is given in the atoms and subscripts section of t
As of STACK 4.4.0, there is an option to check, or allow comparison between, variables which occur in the student's answer and the teacher's answer.
This option takes the form of `checkvars:n`, where `n` is an integer. Ommiting this option is equivalent to setting `n=0`.
This option takes the form of `checkvars:n`, where `n` is an integer. Omitting this option is equivalent to setting `n=0`.
The binary bits are used to set this options.
......@@ -343,7 +343,7 @@ The numerical argument provides potential for future-proofing features (e.g. cas
### Extra option: validator ###
This allows an input to add additional bespoke validation, based on a function defined by the question author. For example, you can define a function which checks if the student's answer is a _list of exactly three floating point numbers_. See the [validator documetation](../CAS/Validator.md) for more details.
This allows an input to add additional bespoke validation, based on a function defined by the question author. For example, you can define a function which checks if the student's answer is a _list of exactly three floating point numbers_. See the [validator documentation](../CAS/Validator.md) for more details.
Writing bespoke validators is an advanced feature, but offers two significant benefits.
......
......@@ -42,7 +42,7 @@ You can control the size of the JSXGraph board with the `width` and `height` opt
[[jsxgraph width="200px" height="200px"]]
The option `aspect-ratio` combinet with the ability to use relative dimensions allows for graphs to resize and maintain its shape if the viewport changes. When using `aspect-ratio` it is necessary to define one and only one of the above lengths.
The option `aspect-ratio` combined with the ability to use relative dimensions allows for graphs to resize and maintain its shape if the viewport changes. When using `aspect-ratio` it is necessary to define one and only one of the above lengths.
[[jsxgraph width="80%" aspect-ratio="3/2"]]
......@@ -284,7 +284,7 @@ Now that the graph has been drawn, we need to initialise the shading based on ex
}
}
The graph should now have the appropriate shading applied. We have completed the first two out of three steps as outlined above. To accomplish the last step we will write three functions; one that will return the coordinates of a location that is clicked, andother that will update the graph given those coordinates, and a third that will listen to a click event and then run these functions.
The graph should now have the appropriate shading applied. We have completed the first two out of three steps as outlined above. To accomplish the last step we will write three functions; one that will return the coordinates of a location that is clicked, another that will update the graph given those coordinates, and a third that will listen to a click event and then run these functions.
/* The below code is adapted from an example found at https://jsxgraph.org/wiki/index.php/Browser_event_and_coordinates */
......
......@@ -46,7 +46,7 @@ An example which includes the `display` option is
Note in this example the `value` of the student's answer will be a letter which is literally a Maxima variable name. In this situation you can't really randomize the letters used easily. (Not impossible with some cunning code, but a lot of work....)
If you choose to use an integer, and randomly suffle the answers then the validation feedback would be confusing, since an integer (which might be shuffled) has no correspondence to the choices selected. *This behaviour is a design decision and not a bug! It may change in the future if there is sufficient demand, but it requires a significant change in STACK's internals to have parallel "real answer" and "indicated answer". Such a change might have other unintended and confusing consequences.*
If you choose to use an integer, and randomly shuffle the answers then the validation feedback would be confusing, since an integer (which might be shuffled) has no correspondence to the choices selected. *This behaviour is a design decision and not a bug! It may change in the future if there is sufficient demand, but it requires a significant change in STACK's internals to have parallel "real answer" and "indicated answer". Such a change might have other unintended and confusing consequences.*
Normally we don't permit duplicate values in the values of the teacher's answer. If the input type receives duplicate values STACK will throw an error. This probably arises from poor randomization. However it may be needed. If duplicate entries are permitted use the display option to create unique value keys with the same display. *This behaviour is a design decision may change in the future.*
......@@ -117,7 +117,7 @@ To enable a student to indicate "none of the others", the teacher must add this
The radio and dropdown types always add a "not answered" option as the first option. This allows a student to retract their choice, otherwise they will be unable to "uncheck" a radio button, which will be stored, validated and possibly assessed (to their potential detriment). If you want to remove this then use the extra option `nonotanswered`, but keep in mind the possible effect when using the penalty scheme.
If one of the items in the teacher's answer list is is the special variable name `notanswered`, and then default mesage `(Clear my choice)` will be replaced by the `display` value. If no `display` value is given (and it is optional) then the original message will remain. `notanswered` will not appear in the list of valid choices for a user and `value` for this input is ingored.
If one of the items in the teacher's answer list is is the special variable name `notanswered`, and then default message `(Clear my choice)` will be replaced by the `display` value. If no `display` value is given (and it is optional) then the original message will remain. `notanswered` will not appear in the list of valid choices for a user and `value` for this input is ingored.
## Extra options ##
......@@ -152,9 +152,7 @@ For example, the question variables might look like the following.
tao:[null, false, "None of these"];
ta:append(ta,[tao]);
These commands ensure (1) the substantive options are in a random order, and (2) that the `None of these` always comes at the end of the list.
Note, the value for the `None of these` is the CAS atom `null`.
In Maxima `null` has no special significance but it is a useful atom to use in this situation.
These commands ensure (1) the substantive options are in a random order, and (2) that the `None of these` always comes at the end of the list. Note, the value for the `None of these` is the CAS atom `null`. In Maxima `null` has no special significance but it is a useful atom to use in this situation.
As the Question Note, you might like to consider just taking the first item from each list, for example:
......@@ -297,7 +295,7 @@ You must protect characters within strings. E.g. in
We have protected the backslash, and the inequality.
The language strings are not CAStext, they are simply raw strings. It is possible to construct strings which inlcude variable values using the `stack_disp` function.
The language strings are not CAStext, they are simply raw strings. It is possible to construct strings which include variable values using the `stack_disp` function.
[oc(-inf,a), false, sconcat("The half interval: ", stack_disp(oc(-inf,a),"i"))]
......@@ -314,7 +312,7 @@ Since 4.4 it has been possible to write more complex labels using inline CASText
You may write normal CASText syntax inside that string and it should behave exactly like it does in question-text or PRT feedback etc.. The only limitation at this time is that the list that includes these labels must be defined in the question-variables, you may not write inline CASText directly to the model answer field of the input. The `castext()`-function is not a real CAS-function it is converted to more complex logic at compile time and therefore it must receive a static string as its argument.
The most obvious use case for inline CASText is to provide localisation inside MCQ labels in situatiosn where the mlang2-filter is not an option:
The most obvious use case for inline CASText is to provide localisation inside MCQ labels in situations where the mlang2-filter is not an option:
[true, true, castext("[[lang code='en']]Yes[[/lang]][[lang code='fi']]Kyllä[[/lang]]")]
......
......@@ -10,7 +10,7 @@ While not everyone uses them and not everyone needs to use them, they do improve
If you are running on a truly large scale or if your servers cannot keep up, always look at [deployed variants](./Deploying.md) first.
Just make your question notes informative, the prefered way is to show the question and the answer for this particular variant in short form; a simple parameter list may help, but it is often less than helpful.
Just make your question notes informative, the preferred way is to show the question and the answer for this particular variant in short form; a simple parameter list may help, but it is often less than helpful.
## Randomisation loops are really bad!
......@@ -27,7 +27,7 @@ If you cannot write code that directly randomises a "good" result, you should us
## Big strings or things you might not want to place in question-variables.
In the STACK question model, it is assumed that whatever is in the question-variables or in any other code/logic block is data and needs to be fully transferred into the CAS during all processing steps of the question; conversely, whatever is present in the question-text or other text content is assumed to be safe and not "data". We do special sidelining of such safe "not data" and don't send it all the way to CAS if we can avoid it, and it still rejoins the output once necessary.
In the STACK question model, it is assumed that whatever is in the question-variables or in any other code/logic block is data and needs to be fully transferred into the CAS during all processing steps of the question; conversely, whatever is present in the question-text or other text content is assumed to be safe and not "data". We do special side-lining of such safe "not data" and don't send it all the way to CAS if we can avoid it, and it still rejoins the output once necessary.
This means that if you place big strings on the logic side without actually using them there, you are probably wasting resources. If that text is intended as something to be outputted in the text itself then one should look at putting it into the text itself, maybe using [CASText features](./Question_blocks/index.md) that allow conditional inclusion if need be.
......
......@@ -2,7 +2,7 @@
Parson’s problems require students to assemble pre-written text into a correct order by dragging blocks into a tree structure. This block is needed to hold the javascript and strings which students can drag.
STACK provides a `[[parsons]] ... [[/ parsons]]` [question block](Question_blocks/index.md). The question author pre-defines strings. These strings can be defined as Maxima variables in the question text, or just defined within the question block itself.
STACK provides a `[[parsons]] ... [[/ parsons]]` [question block](Question_blocks/index.md). The question author pre-defines strings to drag within the block. These strings can be defined as Maxima variables in the question text, or just defined within the question block itself.
Users interact with the strings, dragging them into a tree structure. Note, a list is a special case of a more structured tree. The block can be linked to a STACK input so that the student's configuration can be stored and/or assessed. This page is reference documentation for the `[[parsons]]` block. Documentation on how to use this block in a complete question is given under topics: [Authoring Parson's problems](../Topics/Parsons.md).
......@@ -44,6 +44,8 @@ Both these approaches can be combined
[[/parsons]]
````
Note the `\` character needs to be protected within strings, so for example we have to type `\\(n=2m+1\\)` rather than just `\(n=2m+1\)`.
## Customising the `[[parsons]]` block
### JSON "options"
......@@ -53,7 +55,7 @@ The `[[parsons]]` block is a wrapper for the javascript library "Sortable.js", o
````
[[parsons input="ans1"]]
{ "steps": {# stackjson_stringify(proof_steps) #},
"options": {"header" : ["custom header for the answer list", "custom header for the available steps"],
"options": {"header" : ["Custom header for the answer list", "Custom header for the available steps"],
"sortable option 1" : value,
...
"sortable option n" : value}
......@@ -84,7 +86,7 @@ Note that if you enter an unknown sortable option or if an attempt to pass `ghos
Functionality and styling can be customised through the use of block parameters.
1. `input`: string. The name of the STACK input variable (e.g., `"ans1"`), this links to an internal `state` parameter that updates the input as a Maxima expression so that it can be evaluated by a PRT.
1. `input`: string. The name of the STACK input variable (e.g., `"ans1"`), this links to an internal `state` parameter that updates the input as a Maxima expression so that it can be stored and evaluated by a PRT.
2. `height`: string containing a positive float + a valid CSS unit (e.g.`"480px"`, `"100%"`, ...). Default is to create a window of automatic height to fit all the content upon load. Entering a value for the `height` parameter in the block header fixes the height of the window containing the drag-and-drop lists and will disable automatic resizing of the window containing the lists. Students will still be able to automatically resize the window with the expand button.
3. `width`: string containing a positive float + a valid CSS unit (e.g.`"480px"`, `"100%"`, ...). Default is `"100%"`. This fixes the width of the window containing the drag-and-drop lists.
4. `aspect-ratio`: string, containing a float between 0 and 1. This can be used with `height`/`length` _or_ `width` (not both) and automatically determines the value of the un-used parameter in accordance with the value of `aspect-ratio`; unset by default. An error will occur if one sets values for `aspect-ratio`, `width`, `height` _or_ `aspect-ratio`, `width`, `length`.
......@@ -157,7 +159,7 @@ Notice that since the value of `plot(...)` is a Maxima string of `<img>` tag, th
[[/parsons]]
````
An alternatove is to use the Maxima `castext` function, e.g.
An alternative is to use the Maxima `castext` function, e.g.
s1:castext("Consider this graph {@plot(x^2,[x,-1,1],[size,250,250])@}");
......
......@@ -8,7 +8,7 @@ Each potential response tree relies on one or more of the [inputs](Inputs.md). S
## Before the tree is traversed ##
Each potential response tree can set Maxima's level of [simplification](../CAS/Simplification.md). Before the tree is traversed the [feedback variables](Variables.md#Feedback_variables) are evaluated. The feedback variables may depend on the values of the [question variables](Variables.md#Question_variables) and the [inputs](Inputs.md). The values of these variables are available to the [answer tests](Answer_Tests/index.md) and all [CASText](CASText.md) fields within the tree, for example the feedback could be built using these variables.
Each potential response tree can set Maxima's level of [simplification](../CAS/Simplification.md). Before the tree is traversed the [feedback variables](Variables.md#Feedback_variables) are evaluated. The feedback variables may depend on the values of the [question variables](Variables.md#Question_variable.s) and the [inputs](Inputs.md). The values of these variables are available to the [answer tests](Answer_Tests/index.md) and all [castext](CASText.md) fields within the tree, for example the feedback could be built using these variables.
Notes:
......@@ -26,7 +26,7 @@ In each node two expressions are compared using a specified [answer tests](Answe
2. Add written feedback specifically for the student
3. Generate an "[answer note](Potential_response_trees.md#Answer_note)", used by the teacher for evaluative assessment
4. Nominate the next node, or end the process.
5. Any runtime error during traversing the tree will cause an error. This error will stop further exectution of the tree, and students will see a runtime error message. This will be flagged in the response summary as `[RUNTIME_ERROR]`. If you have statements likely to throw an error you should evaluate them in the feedback variables first. See notes on [error trapping](Error_trapping.md) for advice on how to use this.
5. Any runtime error during traversing the tree will cause an error. This error will stop further execution of the tree, and students will see a runtime error message. This will be flagged in the response summary as `[RUNTIME_ERROR]`. If you have statements likely to throw an error you should evaluate them in the feedback variables first. See notes on [error trapping](Error_trapping.md) for advice on how to use this.
## Outcomes ##
......@@ -51,7 +51,7 @@ This field is given a default value automatically and is used for [reporting](Re
This field may not be empty and for each node in a tree the string must be unique.
Do not use `;`, `|` charaters in your answer note. These characters are used to split the response summary in the reporting scripts.
Do not use `;`, `|` characters in your answer note. These characters are used to split the response summary in the reporting scripts.
## Scores and penalties ##
......@@ -96,7 +96,7 @@ The feedback created by PRTs has the following parts concatenated together.
[Generic feedback] [Runtime errors] [PRT generated feedback] [Score ?]
The `[Generic feedback]` is a question level option, e.g. "Standard feedback for correct", to provide consistency accross a question. By default the `[Generic feedback]` contains both an initial symbol, and a language sentence. The current "correct" default is
The `[Generic feedback]` is a question level option, e.g. "Standard feedback for correct", to provide consistency across a question. By default the `[Generic feedback]` contains both an initial symbol, and a language sentence. The current "correct" default is
<span style="font-size: 1.5em; color:green;"><i class="fa fa-check"></i></span> Correct answer, well done.
......@@ -109,5 +109,5 @@ Value | Options | Symbol | Generic feedback | Errors | PRT feedback | Score
2 | Compact | Yes | No | Yes | Yes | No
3 | Symbol only | Yes | No | Yes | No | No
Note that the "Compact" PRT feedback uses `<span>` tags and not `<div>`. This allows inclusion inline, without new paragraphs settings. However, `<span>` tags cannot contain a block level element, such as a `<div>` or `<p>`. So, if you include a block level element in your PRT feedback then the browser may "spit this out" and misplace the feedback. Also, MathJax may not display mathematics correctly on the page when there is an HTML errror such as this. If you use the "Compact" feedback, please author only minimal PRT feedback with no block level HTML elements.
Note that the "Compact" PRT feedback uses `<span>` tags and not `<div>`. This allows inclusion inline, without new paragraphs settings. However, `<span>` tags cannot contain a block level element, such as a `<div>` or `<p>`. So, if you include a block level element in your PRT feedback then the browser may "spit this out" and misplace the feedback. Also, MathJax may not display mathematics correctly on the page when there is an HTML error such as this. If you use the "Compact" feedback, please author only minimal PRT feedback with no block level HTML elements.
......@@ -62,7 +62,7 @@ the lists or set be shorter/smaller the iteration will stop when the first one e
Because the foreach block needs to evaluate the lists/sets before it can do the iteration, using foreach blocks will require one
additional CAS evaluation for each nested level of foreach blocks. This has not applied since 4.4. no additional cost is related
to this block and it is recommended that any repeption that can be removed is removed using this block.
to this block and it is recommended that any repetition that can be removed is removed using this block.
## Define block {#define-block}
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment